@modus-ai/modus 0.2.4 → 0.2.6

package/templates/commands/spec.md

@@ -1,37 +1,81 @@
-# /modus:spec
+# /modus:spec — 规范驱动开发（OpenSpec 行为规格）
 
-OpenSpec-style spec-driven development. Generate behavior specifications (delta specs) + design + tasks, with archive merging specs into the main spec library.
+**用途：** 在 `/plan` 基础上增加行为规格（delta specs），用 GIVEN/WHEN/THEN 明确系统「WHAT」，规格可测试，归档时自动检测冲突并合并到主规格库（Source of Truth）。适用于有接口契约变更、需要可测试验收标准的场景。
 
-## Instructions
+**借鉴自：** OpenSpec 规范 + Gherkin BDD（Cucumber）的 Feature/Scenario 格式
 
-Read and follow the skill at `.codebuddy/skills/modus-spec/SKILL.md` to execute this command.
+## 参数说明
 
-## Quick Summary
+```
+/modus:spec [需求描述] [参数]
+
+  --help                    显示完整帮助（中文）
+  --story <tapd-url>        关联 TAPD Story（自动填写背景，写入 HANDOFF story_id）
+  --project <name>          指定项目（多项目 workspace 使用）
+  --lite                    轻量模式：跳过 design-brief，仅生成 delta-specs + tasks
+  --delta                   仅生成 delta-specs.md（不生成 design 和 tasks）
+  --testcase                归档前同步生成 QA 测试用例文件（testcases.md，JUnit 5 骨架）
+  --verify                  归档前执行三维验证（完整性/正确性/一致性）
+  --resume <name>           从断点继续（读取 .modus-state.yaml）
+  --no-archive              跳过归档到主规格库（适合实验性变更）
+```
+
+## 使用示例
+
+```
+/modus:spec 新增歌曲批量审批功能
+/modus:spec --story https://tapd.cn/.../stories/view/123 艺人等级评定
+/modus:spec --lite 优化版权查询索引
+/modus:spec --testcase 修改支付超时时间从 30 分钟改为 15 分钟
+/modus:spec --verify --story https://tapd.cn/.../123 电子签约批量重签
+/modus:spec --resume batch-approve 继续上次中断的规格
+```
+
+## 与 `/modus:plan` 的区别
 
-1. Check for business Skills (same fallback as `/modus:vibe`)
-2. Identify relevant business domains
-3. **Pre-update Skills**: refresh relevant business Skill files
-4. Generate specification documents to `modus/changes/{name}/`:
-   - `proposal.md` — intent and scope
-   - `specs/{domain}/spec.md` — delta specs (ADDED/MODIFIED/REMOVED requirements with Scenarios)
-   - `design.md` — technical approach
-   - `tasks.md` — implementation checklist (includes spec verification tasks)
-5. Ask user whether to archive:
-   - Delta specs merged into `modus/specs/` (source of truth)
-   - Change folder moved to `modus/changes/archive/{YYYY-MM-DD}-{name}/`
-6. **Post-update Skills**: write back new business rules and contracts
+| 维度 | `/modus:plan` | `/modus:spec` |
+|------|--------------|----------------|
+| 产出物 | 单一 `plan.md` | `delta-specs.md` + `design.md` + `tasks.md` |
+| 目录 | `modus/plans/{name}/` | `modus/changes/{name}/` |
+| 行为规格 | 无 | 有（ADDED/MODIFIED/REMOVED + GIVEN/WHEN/THEN） |
+| 验收标准 | 无 | 有（可测试 Scenario） |
+| 冲突检测 | 无 | 有（MODIFIED/REMOVED 目标必须存在于主库） |
+| 归档目标 | `modus/plans/archive/` | 合并到 `modus/specs/{domain}/spec.md` |
 
-## Delta Spec Format
+## Delta Specs 格式（Gherkin 风格）
 
-Use ADDED/MODIFIED/REMOVED sections with GIVEN/WHEN/THEN scenarios.
-Specs describe WHAT the system does, not HOW.
+```markdown
+Feature: 批量审批订单
 
-## Output Location
+## ADDED Requirements
+
+### Scenario: Happy Path
+  Given 用户已登录且拥有审批权限
+  When 提交包含 ≥1 条订单 ID 的批量审批请求
+  Then 所有订单状态变更为 APPROVED，返回成功数量
+
+### Scenario: 超出上限
+  Given 请求包含 > 50 条订单 ID
+  When 提交批量审批请求
+  Then 系统返回 400 错误："批量操作上限 50 条"
+```
+
+## 产出物
 
 ```
 modus/changes/{name}/
-├── proposal.md
-├── specs/{domain}/spec.md    ← delta specs
-├── design.md
-└── tasks.md
+├── .modus-state.yaml               — 状态文件（支持断点续跑）
+├── proposal.md                     — 意图与范围
+├── specs/{domain}/spec.md          — delta specs（ADDED/MODIFIED/REMOVED）
+├── design.md                       — 技术方案
+├── design-brief.md                 — 精确实现指南（Full 模式）
+├── tasks.md                        — 实现清单（追踪到 Scenario）
+└── testcases.md                    — QA 用例（--testcase 时生成）
+
+归档后：modus/changes/archive/{date}-{name}/
+主规格库：modus/specs/{domain}/spec.md（历次归档合并）
 ```
+
+## 执行此命令
+
+读取并执行 `.codebuddy/skills/modus-spec/SKILL.md` 中的完整流程。

package/templates/commands/upgrade.md

@@ -0,0 +1,54 @@
+# /modus:upgrade — 框架版本升级
+
+**用途：** 检测 Modus 框架新版本，自动执行目录结构迁移和 Skill 格式升级，保持项目与最新规范一致。
+
+## 参数说明
+
+```
+/modus:upgrade [参数]
+
+  --help                    显示完整帮助（中文）
+  --check                   仅检查当前版本和最新版本，不执行升级
+  --dry-run                 预览将修改哪些文件，不实际写入
+  --changelog               显示从当前版本到最新版的变更日志
+  --target <version>        升级到指定版本（默认最新稳定版）
+  --project <name>          仅升级指定项目的 Skill 文件（多项目时）
+  --migrate-only            仅执行文件结构迁移，不更新框架 Skill 模板
+  --backup-dir <path>       指定备份目录（默认 modus/backup/{date}/）
+  --force                   强制升级（即使版本一致，用于修复损坏的文件）
+```
+
+## 使用示例
+
+```
+/modus:upgrade                     # 检查并执行升级到最新版
+/modus:upgrade --check             # 仅检查当前和最新版本
+/modus:upgrade --dry-run           # 预览升级变更，不实际修改
+/modus:upgrade --changelog         # 查看版本变更说明
+/modus:upgrade --target 3.2.0      # 升级到指定版本
+/modus:upgrade --migrate-only      # 仅迁移目录结构，不更新模板
+```
+
+## 版本迁移说明
+
+| 版本 | 主要变更 |
+|------|---------|
+| v3.2.0 | 跨 Skill 路径全面统一到 `modus/knowledge/biz-*/`；步骤编号规范化（禁止小数步骤）；modus-analyst 产出路径更正到 `modus/stories/{id}/harness/`；modus-plan 双路径产出规则（Story 模式 vs 独立模式） |
+| v3.1.0 | 知识库路径迁移：`.codebuddy/skills/modus-biz-*` → `modus/knowledge/biz-*`；新增工作区顶层路由 `modus/workspace-catalog.md`；HANDOFF 协议升级到 schema v1.1 |
+| v3.0.0 | 多项目工作区支持（modus-workspace.yaml）；引用式适配（不复制知识） |
+| v2.x | 初始版本 |
+
+## 升级流程
+
+```
+① 读取本地 modus/config.yaml 的 modus_version 字段
+② 对比目标版本，展示差异摘要
+③ 询问确认（--force 时跳过）
+④ 备份现有文件到 modus/backup/{date}/
+⑤ 执行迁移：文件结构调整 + Skill 格式更新
+⑥ 输出迁移完成报告
+```
+
+## 执行此命令
+
+读取并执行 `.codebuddy/skills/modus-upgrade/SKILL.md` 中的完整流程。

package/templates/commands/vibe.md

@@ -1,12 +1,24 @@
-# /modus:vibe
+# /modus:vibe — 上下文感知编码（氛围编程）
 
-Context-aware vibe coding. Intelligently loads relevant business Skills, auto-syncs stale knowledge, and applies rule-driven clarification before coding so AI works as a knowledgeable project member.
+**用途：** 执行日常编码任务前，自动加载相关业务 Skill，让 AI 以「懂项目的开发者」身份工作，而非冷启动。适合 Bug 修复、小功能迭代、代码重构等日常任务。
 
-## Instructions
+> Context-aware vibe coding. Intelligently loads relevant business Skills, auto-syncs stale knowledge, and applies rule-driven clarification before coding so AI works as a knowledgeable project member.
 
-Read and follow the skill at `.codebuddy/skills/modus-vibe/SKILL.md` to execute this command.
+## 参数说明
 
-## Quick Summary
+```
+/modus:vibe [需求描述] [参数]
+
+  --help                    显示完整帮助（中文）
+  --domain <name>           强制加载指定业务域（跳过自动匹配，如 --domain biz-track）
+  --project <name>          指定项目（多项目 workspace 使用）
+  --context <file>          额外加载指定文件作为上下文（相对路径）
+  --no-skill                跳过 Skill 加载，直接用原始代码上下文（不推荐）
+  --verbose                 显示 Skill 加载过程和 token 预估
+  --dry-run                 仅展示将加载的 Skill 和文件，不执行编码
+```
+
+## 执行流程（概览）
 
 1. Read `modus/config.yaml` for hard constraints (constitution)
 2. Load `modus/knowledge-catalog.md` (Level 1, ~200 tokens)
@@ -16,7 +28,45 @@ Read and follow the skill at `.codebuddy/skills/modus-vibe/SKILL.md` to execute
 6. Load matched Skill files as context (Level 2, ~3000 tokens each)
 7. **Adaptive Design Brief**: Simple tasks → 3-section inline brief; Medium/Complex → full 9-section brief
 8. Execute the coding task with business context (Level 3 on-demand file reads)
-9. **Auto Skill write-back** (silent): if new knowledge discovered, call skill-creator Mode C to persist; show one-line `[已更新 {domain} 域知识: ...]`; if nothing new, stay silent
+9. **Buffer new knowledge** (silent): if new knowledge discovered (new enums, pitfalls, rule changes), append to `modus/sessions/pending-knowledge.yaml`; show one-line `[缓冲 {N} 条新知识 → 将在 /modus:commit 时沉淀到 Skill]`; if nothing new, stay silent. **Do NOT write to Skill files directly** — run `/modus:commit` to persist buffered knowledge.
 10. Append session log to `modus/sessions/vibe-log.md`
 
 **Degraded mode** (no business Skills): proceed without domain context, note quality may be lower, show `[降级模式：无业务上下文，建议先运行 /modus:init]`.
+
+## 使用示例
+
+```
+/modus:vibe 给歌曲列表接口加一个按状态筛选的功能
+/modus:vibe 订单支付回调逻辑有个 NPE，帮我排查
+/modus:vibe --domain biz-track 重构歌曲同步的重试机制
+/modus:vibe --verbose 分析专辑发行流程的性能瓶颈
+/modus:vibe --dry-run 优化版权审核的并发处理
+```
+
+## 知识加载策略（渐进三级）
+
+```
+Level 1（必须，~200 tokens）
+  读 modus/knowledge-catalog.md
+  → 了解可用知识域，匹配当前任务相关域
+
+Level 2（按需，~3000 tokens/个）
+  仅读与任务语义匹配的 modus/knowledge/biz-*/SKILL.md
+  → 不相关的域不加载，节省 ~59% token
+
+Level 3（执行时，无上限）
+  从 Skill 的 key_files 索引按需读取实际代码文件
+  → 绝不预先全量读取
+```
+
+## 无业务 Skill 时的兜底
+
+```
+⚠️ 未找到业务知识库！建议先运行：/modus:init
+A. 现在运行快速初始化
+B. 继续（无业务上下文，结果质量可能降低）
+```
+
+## 执行此命令
+
+读取并执行 `.codebuddy/skills/modus-vibe/SKILL.md` 中的完整流程。

package/templates/knowledge-catalog.md

@@ -1,53 +1,95 @@
-# Modus 知识全景目录
+# Modus 知识全景目录 — {project-name}
 # 所有 Modus 命令启动时先读此文件（Level 1 加载，~200 tokens）
-# 按需再读完整 SKILL.md（Level 2），或直接读代码文件（Level 3）
+# 框架版本：3.1.0 | 知识库路径：{project}/modus/knowledge/**（Single Source of Truth）
+# 多平台适配：CLAUDE.md / AGENTS.md / .cursor/rules/ 均为引用式，修改请直接编辑 modus/knowledge/ 下的文件
 #
-# maturity: draft → verified → proven
-# 衰减：proven 12个月未引用→verified；verified 6个月未引用→draft
+# 路由层级：
+#   workspace → modus/workspace-catalog.md（顶层，~100 tokens）
+#   project   → 本文件（~200 tokens）
+#   domain    → modus/knowledge/biz-*/SKILL.md（~3000 tokens/个，按需加载）
+# 按需再读完整 SKILL.md（Level 2，~3000 tokens/个）
+# 或直接读 Skill 引用的实际代码文件（Level 3，按需）
 
 updated: {YYYY-MM-DD}
 
+## 全局行为守卫 (Layer 0-G)
+# 所有命令 Step 0 加载，优先级：低于 constitution.hard_rules，高于 Skill 建议
+- **behavior-guard**: `modus/behavior-guard.md` — 五条全局行为约束
+  (Think Before Coding · Simplicity First · Surgical Changes · Goal-Driven Execution · Token Budget Guard)
+  [由 /modus:init 生成，不随项目代码变化，手动维护]
+
 ## 团队约定 (Layer 0-T)
-- **modus-team-conventions**: 代码规范/提交规范/硬性约束 [maturity: draft] 更新: {日期}
+- **_conventions**: {规范描述} [maturity: draft] 更新: {日期}
+  - 路径：`{project}/modus/knowledge/_conventions/SKILL.md`
 
 ## 技术知识 (Layer 1)
-- **modus-tech-wiki**: 跨项目架构决策/反模式库/性能优化 [maturity: draft] 更新: {日期}
+- **_tech-wiki**: {技术栈描述} [maturity: draft] 更新: {日期}
+  - 路径：`{project}/modus/knowledge/_tech-wiki/SKILL.md`
 
 ## 业务知识 (Layer 2)
 <!-- 由 /modus:init 生成，由各模式工作流自动更新 -->
-- **modus-biz-{domain}**: {中文域名} — {核心职责一句话} [maturity: draft] 最近引用: {日期}
+- **biz-{domain}**: {中文域名} — {核心职责一句话} [maturity: draft] 最近引用: {日期}
+  - 路径：`{project}/modus/knowledge/biz-{domain}/SKILL.md`
+
+## 域依赖图 (Dependency Graph)
+<!--
+  格式：{下游域} --> {上游域1}, {上游域2}
+  含义：下游域的 Skill 中 upstream_skills 声明了对上游域的依赖。
+  当上游域 hash 变更时，下游域的 stale_cascade 自动置为 true（在 ⚠️ 标注处可见）。
+  由 /modus:init 自动生成，可手动补充跨域调用关系。
+-->
+<!-- example:
+  payment --> order, user
+  notification --> order, payment
+  report --> order, payment, user
+-->
+<!-- 当前依赖关系（/modus:init 扫描后填入）：
+  {待填入}
+-->
 
 ## 渐进加载说明
+
 启动任意 Modus 命令时的加载顺序：
-  Level 1（必须，~200 tokens）: 读本文件，了解有哪些知识可用
-  Level 2（按需，~3000 tokens/个）: 根据任务匹配相关域，读对应 SKILL.md
-  Level 3（按需，无上限）: 执行任务时读 Skill 引用的实际代码文件
+  Level 1（必须，~200 tokens）:  读本文件，了解有哪些知识可用
+  Level 2（按需，~3000 tokens）: 根据任务匹配相关域，读对应 SKILL.md
+  Level 3（按需，无上限）:       执行任务时读 Skill 引用的实际代码文件
 
 目标：不相关的 Skill 不加载，大幅降低 token 消耗。
 
-## Skill 状态生命周期
+## 框架命令（快速参考）
+- **modus:init** `--help` `--enhance [domain]` `--enhance-all` `--migrate` `--dry-run` `--force` `--platform [list]` `--no-sync` `--verbose` `--reset-maturity` `--project [name]`
+- **modus:vibe** `--help` `--domain [name]` `--project [name]` `--context [file]` `--no-skill` `--verbose` `--dry-run`
+- **modus:plan** `--help` `--story [url]` `--design` `--quick` `--enhance` `--no-build` `--resume [name]` `--complexity [level]` `--project [name]`
+- **modus:spec** `--help` `--story [url]` `--lite` `--delta` `--testcase` `--verify` `--resume [name]` `--no-archive` `--project [name]`
+- **modus:auto** `--help` `--force [mode]` `--no-confirm` `--show-scores` `--project [name]`
+- **modus:harness** `--help` `--story [url]` `--skip [agents]` `--loop1-only` `--resume` `--dry-run` `--force-rebuild-skill` `--no-deploy` `--max-loop2 [n]` `--notify [channel]` `--project [name]`
+- **modus:upgrade** `--help` `--check` `--dry-run` `--changelog` `--target [version]` `--project [name]`
+
+## Skill status 生命周期
 
-### 成熟度状态（基于 usage_count）
-- **draft**    → 初始生成，未经验证（usage_count = 0）
-- **verified** → 经至少1次真实使用验证（usage_count ≥ 1，运行 `/modus:verify` 升级）
-- **proven**   → 经≥2个不同工作流验证有效（usage_count ≥ 2）
-- **stale**    → last_hash 不匹配或距 last_referenced 超过 stale_after_days，需更新（禁止直接引用）
-- **archived** → 域已废弃，不再维护
+| status    | 含义                    | 升级方式                          |
+|-----------|-------------------------|-----------------------------------|
+| draft     | 初始生成，未经验证       | 运行 /modus:verify 且满足四项条件  |
+| verified  | 经至少 1 次真实使用验证  | usage_count ≥ 2 且不同工作流       |
+| proven    | 经 ≥2 个不同工作流验证  | -                                  |
+| stale     | hash 不匹配或衰减超期   | 运行 /modus:refresh 后回到 draft   |
+| archived  | 域已废弃，不再维护       | -（禁止引用）                      |
 
-### 衰减规则（基于 last_referenced）
-- proven  + 距 last_referenced 超过 12 个月 → verified
-- verified + 距 last_referenced 超过 6 个月 → stale
-- stale   + 距 last_referenced 超过 stale_after_days → archived（需人工二次确认）
+## 衰减规则（活跃度感知，基于 last_referenced + usage_count）
+
+衰减阈值根据 usage_count 动态调整：
+- 活跃域（usage_count ≥ 10）：verified → stale 12个月 / proven → verified 24个月
+- 正常域（usage_count 3-9）：verified → stale 6个月 / proven → verified 12个月
+- 冷门域（usage_count ≤ 2）：verified → stale 3个月 / proven → verified 6个月
+- stale + 超过 stale_after_days 天 → archived（需人工二次确认）
+
+## 防腐机制核心字段
 
-### 防腐机制核心字段
 每个 Skill frontmatter 必须包含以下字段，缺一不可：
-- **last_referenced**: 最后引用时间（用于衰减计算）
-- **usage_count**: 使用次数（用于成熟度升级）
-- **last_hash**: key_files 内容 SHA-1 哈希（用于检测代码变更，初始留空）
-- **key_files**: 关键源文件列表（最多20个，用于 hash 计算）
-
-缺少任一防腐字段将导致：
-- 无法自动检测代码变更
-- 无法触发 Skill 更新
-- 无法计算知识衰减
-- 防腐机制完全失效
+- **last_referenced**: 最后引用时间（每次被命令加载时更新）
+- **usage_count**: 使用次数（每次完成真实开发任务后 +1）
+- **last_hash**: 全局 SHA-1（对每个文件单独计算 SHA-1，将「路径:SHA-1」对按文件路径字母序排序后拼接，再整体计算 SHA-1，禁止内容直接拼接）；引用时快速比对，不一致则展开 file_hashes 逐文件定位
+- **file_hashes**: 文件级 hash map（`{路径: SHA-1}`）；全局 hash 不一致时使用，精准输出变更文件清单
+- **key_files**: 关键源文件列表（最多 20 个，用于 hash 计算）
+
+详细说明见：modus/templates/skills/modus-init/SKILL.md「防腐机制总览」章节

package/templates/skills/modus-agents/analyst/SKILL.md

@@ -9,7 +9,7 @@ disable: false
 
 **调用方：** Harness Orchestrator（`modus-harness`）  
 **输入：** TAPD Story URL + 相关业务 Skill 内容  
-**产出物：** `modus/plans/active/{story-id}/01-analysis.md`
+**产出物：** `modus/stories/{story-id}/harness/01-analysis.md`
 
 ## 职责
 
@@ -23,7 +23,7 @@ disable: false
 
 1. 从 TAPD Story URL 获取需求内容（标题、描述、验收标准）
 2. 读取 Orchestrator 传入的相关业务 Skill 文件
-3. 读取 `modus/config.yaml` 中的项目背景信息
+3. 使用 Orchestrator 传入的 constitution 内容（来自 `{project}/modus/config.yaml`，无需独立读取）
 
 ### Step 2：业务分析
 
@@ -95,7 +95,19 @@ disable: false
 ## 产出物格式（01-analysis.md）
 
 ```markdown
-# 需求分析报告
+---
+schema_version: "1.1"
+agent: "01-analysis"
+run_id: "{YYYYMMDD}-{story_id_prefix}"
+story_id: "{story-id}"
+task_id: ""
+domains: ["{domain1}", "{domain2}"]
+gate_status: "{passed|failed}"
+artifact_status: "complete"
+issues: []
+skill_refs:
+  - "modus-biz-{domain}@{version}"
+---
 
 ## 基本信息
 - Story ID: {id}
@@ -140,3 +152,6 @@ disable: false
 - 每个风险点必须附带处理建议
 - Sprint 计划必须可直接指导 SubAgent 02 开发，不能含糊
 - 验收标准必须可测试（能直接写成测试用例）
+- **HANDOFF 块必须位于文件最顶部（YAML frontmatter 形式，`---...---`）**，`gate_status` 字段不可省略
+- `gate_status` 赋值规则：分析完整且无重大歧义 → `passed`；存在无法确认的关键信息 → `failed`（Orchestrator 会重入本 SubAgent）
+- `risk_level` 取值：有事务/并发/数据迁移风险 → `high`；有接口变更但逻辑清晰 → `medium`；纯新增无破坏 → `low`

package/templates/skills/modus-agents/deployer/SKILL.md

@@ -1,108 +1,160 @@
 ---
 name: modus-deployer
-description: Use this skill when the Harness orchestrator needs to verify deployment after code review passes (no P1/P2 issues). Monitors CI/CD pipeline status, validates service health across environments (dev→uat→pre→prd), runs smoke tests on P0 interfaces, and generates 07-deploy-status.md. Triggered by modus-harness after Gate C passes.
-allowed-tools: Read, Write, Glob, Bash, WebFetch
+description: Use this skill when the Harness orchestrator needs to verify deployment after code review passes. Monitors CI/CD pipeline status, validates service health across gray environments (dev→uat→pre→prd), runs P0 smoke tests, monitors error logs for 30 minutes after go-live, pauses for human confirmation before prd. Generates 07-deploy-status.md with HANDOFF block. Triggered by modus-harness after Gate C passes.
+allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
 
 # modus-deployer（部署发布 SubAgent）
 
 **调用方：** Harness Orchestrator（Gate C 通过后触发）  
-**输入：** `cr-report.md`（无 P1/P2）+ `02-sprint-contract.md`  
+**输入：** `02-sprint-contract.md` + `modus/config.yaml` 的 harness.environments 配置  
 **产出物：** `modus/plans/active/{story-id}/07-deploy-status.md`
 
 ## 职责
 
-代码合入后的灰度部署验证。监控 CI/CD 流水线，验证各灰度环境服务健康状态，对关键接口执行冒烟测试，监控上线后错误日志变化。
+验证代码从 CI 到逐级灰度环境的部署过程，执行 P0 接口冒烟测试，监控上线后错误日志，prd 环境等待人工确认后才执行。
 
 ---
 
 ## 执行流程
 
-### Step 1：确认部署前提
+### Step 1：读取部署配置
 
-1. 确认 `cr-report.md` 结论为「可合入」（无 P1/P2）
-2. 读取 `modus/config.yaml` 中的部署相关配置（如 CI 地址、环境列表）
-3. 提示用户确认已触发 CI/CD 流水线
+读取 `modus/config.yaml`：
+```yaml
+harness:
+  buildCommand: "mvn clean compile -q"
+  environments: [dev, uat, pre]  # prd 单独人工确认
+tapdProjectId: "{TAPD项目ID}"
+```
+
+读取 `02-sprint-contract.md` 的 `changed_files`，确认本次变更的模块范围。
+
+### Step 2：CI 状态轮询
+
+检查 CI/CD 流水线（如有 API/CLI 访问权限）：
+
+```bash
+# 轮询 CI 状态（每 30 秒检查一次，超时 10 分钟）
+# 根据项目 CI 工具配置具体命令
+```
+
+**若 CI 失败：**
+```
+❌ CI 失败，Harness 无法继续部署验证。
+请检查：{CI 失败的 job 和错误摘要}
+修复后重新运行 /modus:harness（断点续跑）。
+⏸️ 等待用户处理。
+```
+
+### Step 3：逐环境灰度验证
+
+按 `harness.environments` 顺序逐级验证（dev → uat → pre）：
+
+**每个环境的验证步骤：**
+
+1. **服务健康检查：** 确认服务实例正常启动（健康检查接口返回 200）
+2. **P0 冒烟测试：** 执行核心接口的基本功能验证（从 01-analysis.md 验收标准选取最关键的 1-3 个场景）
+3. **错误日志监控：** 检查部署后 5 分钟内是否有新增 ERROR 日志（基线对比）
 
-### Step 2：CI 流水线状态监控
+**冒烟测试规范：**
+```bash
+# 从 01-analysis.md 的验收标准提取 P0 场景
+# 使用 curl / HTTP 客户端执行请求
+# 验证响应码和关键字段
+```
+
+**环境验证通过条件：**
+- 健康检查接口返回 200
+- P0 冒烟测试全部通过
+- 5 分钟内新增 ERROR 日志数 ≤ 基线的 110%（允许少量噪音）
 
-定期询问或读取 CI 状态：
-- 构建是否通过
-- 单元测试是否通过
-- 代码扫描是否通过
+**环境验证失败 → 立即停止，上报 Orchestrator 等待人工介入。**
 
-若 CI 失败，输出失败原因并停止。
+### Step 4：⏸️ prd 人工确认
 
-### Step 3：灰度环境验证
+pre 环境验证通过后，暂停等待人工确认：
+
+```
+✅ pre 环境验证通过
+  冒烟测试: {N}/{N} 通过
+  错误日志: 无新增 ERROR
 
-按 `dev → test → pre（预发）` 顺序验证（不自动部署 prd，prd 需人工确认）：
+⏸️ prd 部署等待人工确认：
+
+变更摘要：
+  - 涉及模块: {模块列表}
+  - 变更文件: {N} 个
+  - 已验证环境: dev ✅ | uat ✅ | pre ✅
+
+是否继续部署到 prd？[Y/n]
+```
 
-对每个环境：
-1. 检查服务健康状态（health check 接口）
-2. 执行 P0 冒烟测试（来自 `01-analysis.md` 的验收 Scenario）
-3. 查询近 15 分钟 ERROR 日志数量，与上线前基线对比
+等待用户确认后继续。
 
-### Step 4：生成部署报告
+### Step 5：prd 上线监控（仅在用户确认后执行）
+
+prd 部署后监控 30 分钟：
+- 每 5 分钟检查一次 ERROR 日志数量
+- 若 ERROR 数量显著增加（> 基线 150%），立即告警并暂停
+
+### Step 6：写入部署状态报告
 
 ---
 
 ## 产出物格式（07-deploy-status.md）
 
 ```markdown
-# 部署状态报告
+<!--HANDOFF
+agent: "07-deployer"
+story_id: "{story-id}"
+gate_status: "{passed|failed|pending_prd}"
+environments_passed: ["{dev}", "{uat}", "{pre}"]
+prd_status: "{deployed|pending|skipped}"
+-->
+
+# 部署状态报告 — {Story 标题}
 
-## 基本信息
-- Story ID: {id}
+## 部署摘要
 - 部署时间: {YYYY-MM-DD HH:mm}
-- 代码分支: {branch}
+- 触发版本: {commit hash 或构建号}
+- 最终状态: {✅ 全部通过 / ❌ 失败 / ⏸️ 等待 prd}
 
-## CI 流水线
-| 阶段 | 状态 | 耗时 |
-|------|------|------|
-| 构建 | ✅ | {N}s |
-| 单元测试 | ✅ | {N}s |
-| 代码扫描 | ✅ | {N}s |
+## 环境验证结果
 
-## 灰度环境验证
+| 环境 | 健康检查 | 冒烟测试 | ERROR日志 | 结论 |
+|-----|---------|---------|---------|-----|
+| dev | ✅ | ✅ N/N | 无新增 | ✅ 通过 |
+| uat | ✅ | ✅ N/N | 无新增 | ✅ 通过 |
+| pre | ✅ | ✅ N/N | 无新增 | ✅ 通过 |
+| prd | ⏸️ 待确认 | — | — | ⏸️ 等待人工 |
 
-### dev 环境
-- 服务状态: ✅ 健康
-- 冒烟测试: {N}/{N} 通过
-- ERROR 日志: 上线前 {N}/h → 上线后 {N}/h（{变化}）
+## 冒烟测试详情
 
-### test 环境
-- 服务状态: ✅ 健康
-- 冒烟测试: {N}/{N} 通过
+### P0 场景：{场景名}
+- 请求: `{HTTP Method} {path}` 
+- 响应: HTTP 200，{关键字段验证}
+- 结果: ✅ 通过
 
-### pre（预发）环境
-- 服务状态: ✅ 健康
-- 冒烟测试: {N}/{N} 通过
-- ERROR 日志: 上线前 {N}/h → 上线后 {N}/h
+## prd 监控日志（上线后 30 分钟）
 
-## prd 环境
-⏸️ 等待人工确认部署
+{prd 部署后补充}
 
-**部署确认单：**
-- [ ] pre 环境验证通过
-- [ ] 业务方确认冒烟通过
-- [ ] 运维确认资源充足
+## 部署注意事项
 
-## 冒烟测试详情
-| 场景 | 接口 | 状态 |
-|------|------|------|
-| {验收场景1} | POST /api/v1/{path} | ✅ |
-| {验收场景2} | GET /api/v1/{path} | ✅ |
-
-## 结论
-{✅ 灰度验证通过，可推进 prd 部署}
-{❌ 灰度验证失败: {失败原因}}
+{记录部署过程中发现的特殊情况，供知识沉淀使用}
 ```
 
+**`gate_status` 赋值规则：**
+- `passed`：所有非 prd 环境通过，prd 也已完成且监控正常
+- `pending_prd`：non-prd 通过，prd 等待人工确认（正常状态）
+- `failed`：任一环境验证失败或 prd 上线后出现 ERROR 激增
+
 ---
 
-## 注意事项
+## 质量标准
 
-- prd 环境不自动部署，必须等待人工确认
-- 若任意灰度环境冒烟失败，立即停止并上报给 Orchestrator
-- ERROR 日志增量超过基线 2 倍时，触发告警提示
+- 冒烟测试场景必须来自 01-analysis.md 的验收标准，不得自行编造
+- prd 环境**必须等待人工确认**，不得自动部署
+- **HANDOFF 块必须位于文件最顶部**，Orchestrator 读取 `prd_status` 决定是否进入 ARCHIVE 阶段