@dtt_siye/atool 1.3.0 → 1.4.0

package/skills/project-analyze/phases/phase2.5-refine.md

@@ -0,0 +1,293 @@
+# Phase 2.5: REFINE（精炼链 — AI sub-agents ≤5 并行）
+
+**目标**：对 Phase 2 生成的模块初稿，串联 requirements-writer 和 software-architecture 的 Refine Mode 进行精炼，将初稿升级为专业级交付文档。
+
+**并发上限**：最多 5 个模块同时精炼。每个模块内部串行（PRD 精炼 → 架构精炼）。
+
+---
+
+## 前置检查
+
+1. `analysis-state.json` 中 `phases.phase2_understand == "completed"`
+2. 读取 `stack` 用于 conventions 加载
+3. 如果 `phases.phase2_5_refine == "completed"` 且非 `--force`，跳过本 Phase
+4. 如果 `--skip-refine`，跳过本 Phase
+
+## 输入数据
+
+| 来源 | 文件 |
+|------|------|
+| Phase 2 模块文档 | `atool-analysis/modules/*/README.md`, `api.md`, `data-model.md`, `dev-guide.md`, `prd.md`, `test-cases.md` |
+| Phase 2 结构化数据 | `.atool-docs/modules/*/data.json` |
+| Conventions | `~/.claude/skills/{stack}-conventions/SKILL.md`（仅 Architecture + API Design 节） |
+
+## 执行流程
+
+### 2.5.1 加载 Conventions 上下文
+
+```bash
+# 从 state.json 读取技术栈
+STACK=$(jq -r '.stack // "generic"' .atool-docs/analysis-state.json)
+```
+
+从对应 conventions SKILL.md 中提取以下章节内容（不加载全文，控制在 ~200 行）：
+- `## Architecture` 或 `## 架构` 章节
+- `## API Design` 或 `## API 设计` 章节
+
+存为 `{conventions_context}` 变量。如果对应 conventions skill 不存在，`{conventions_context}` 为空字符串。
+
+### 2.5.2 构建模块精炼队列
+
+```bash
+# 读取模块列表，按重要性降序排列
+MODULES=$(jq -r '.modules | sort_by(-.importance) | .[].name' .atool-docs/pre-scan/manifest.json)
+```
+
+**断点续传检查**：对每个模块读取 `refine_status.{module}`：
+
+| 状态 | 行为 |
+|------|------|
+| `arch_refine == "completed"` | 跳过该模块 |
+| `prd_refine == "completed"` 且 `arch_refine != "completed"` | 加入队列，从架构精炼开始 |
+| `prd_refine != "completed"` | 加入队列，从 PRD 精炼开始 |
+| `degraded == true` | 跳过（除非 `--force`） |
+
+### 2.5.3 Gate 1: 初稿完整性检查（Hard Gate）
+
+**对每个待精炼模块执行**：
+
+检查项：
+- `atool-analysis/modules/{name}/prd.md` 存在且 ≥ 30 行
+- `atool-analysis/modules/{name}/README.md` 存在
+- `.atool-docs/modules/{name}/data.json` 存在且是合法 JSON
+
+**失败处理**：该模块不进入精炼队列，记录 `refine_status.{name}.gate1 = "failed"`，打印警告，其他模块继续。
+
+### 2.5.4 批量派发精炼 Sub-Agents
+
+**每批最多 5 个模块并行**，每个模块的精炼链为串行两步。等待当前批次全部完成后再派发下一批。
+
+---
+
+#### Step A: requirements-writer Refine（PRD 精炼）
+
+为每个模块派发 sub-agent，prompt 模板：
+
+```
+你是 requirements-writer 的精炼模式（Refine Mode）。
+
+## 任务
+将以下模块的 PRD 初稿精炼为标准 8 节结构。
+
+## 模块信息
+- 模块名：{module_name}
+- 模块路径：{module_path}
+- 技术栈：{detected_stack}
+
+## 输入文件（必须全部读取）
+- atool-analysis/modules/{module_name}/prd.md — Phase 2 初稿
+- atool-analysis/modules/{module_name}/api.md — 接口定义
+- atool-analysis/modules/{module_name}/data-model.md — 数据模型（可能不存在，跳过）
+- .atool-docs/modules/{module_name}/data.json — 结构化数据
+
+## 编码规范约束
+{conventions_context}
+
+## 精炼规则
+**必须读取并遵循**：`~/.claude/skills/requirements-writer/SKILL.md` 中的 **Refine Mode（精炼模式）** 章节。该章节定义了标准的 PRD 精炼流程和输出格式。按照其中的精炼规则逐条执行。
+
+补充说明（与 Refine Mode 保持一致）：
+- 保留初稿 §1-§3 和原 §4 非目标（移至 §6）
+- 补全 §4 数据需求、§5 跨模块依赖、§7 风险与假设、§8 需求追溯矩阵
+- 增强 §2 加 FR-{MOD}-NNN 编号 + Given-When-Then AC + UI 交互表；§3 加 NFR-{MOD}-NNN 编号，标注 [待系统级确认]
+- 输出必须包含完整 8 节结构
+
+## 输出
+原地覆盖 atool-analysis/modules/{module_name}/prd.md
+
+## 禁止行为
+- 不做交互式问答
+- 不修改 README.md / api.md / data-model.md / dev-guide.md / test-cases.md
+- 不创建新文件
+```
+
+完成后立即写入 checkpoint（使用唯一临时文件避免并发竞争）：
+
+```bash
+TMP_FILE=".atool-docs/analysis-state.json.tmp.{module_name}"
+jq --arg mod "{module_name}" \
+   '.refine_status[$mod].prd_refine = "completed"' \
+   .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
+```
+
+---
+
+#### Gate 2: PRD 覆盖率门禁（Hard Gate）
+
+**对每个模块的精炼后 prd.md 执行**：
+
+检查项（每项 20 分，满分 100）：
+
+| 检查项 | 验证方式 | 分值 |
+|--------|---------|------|
+| 8 节结构完整 | `grep -c "^## [0-9]"` ≥ 8 | 20 |
+| FR 编号存在 | `grep -c "FR-"` ≥ 1 | 20 |
+| Given-When-Then AC | `grep -c "Given\|When\|Then"` ≥ 3 | 20 |
+| NFR 编号存在 | `grep -c "NFR-"` ≥ 1 | 20 |
+| 数据需求填充 | §4 非空（> 3 行） | 20 |
+
+**通过**（≥ 70 分）→ 记录分数到 `refine_status.{name}.prd_coverage`，进入 Step B
+
+**失败**（< 70 分）→ 提供恢复选项：
+
+```
+❌ Gate 2 失败：模块 {module_name} PRD 覆盖率 {score}%（需 ≥ 70%）
+   缺失项：{列出具体未通过的检查项}
+
+   恢复选项：
+   [A] 重跑该模块的 PRD 精炼（自动重试 1 次）
+   [B] 手动编辑 prd.md 后输入 "继续" 
+   [C] 降级：跳过精炼，使用 Phase 2 初稿（标记 [未精炼]）
+```
+
+选择 A 时：重新派发 Step A sub-agent（仅 1 次重试，再失败则自动降级）
+选择 C 时：`refine_status.{name}.degraded = true, degraded_reason = "PRD coverage {score}% below threshold"`
+
+```bash
+# Gate 2 通过时写入（使用唯一临时文件）
+TMP_FILE=".atool-docs/analysis-state.json.tmp.{module_name}.gate2"
+jq --arg mod "{module_name}" --argjson score {score} \
+   '.refine_status[$mod].prd_coverage = $score | .refine_status[$mod].prd_gate = "passed"' \
+   .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
+```
+
+---
+
+#### Step B: software-architecture Refine（架构精炼）
+
+仅对通过 Gate 2 的模块执行。为每个模块派发 sub-agent，prompt 模板：
+
+```
+你是 software-architecture 的精炼模式（Refine Mode）。
+
+## 任务
+在以下模块的 dev-guide.md 基础上追加架构章节。
+
+## 模块信息
+- 模块名：{module_name}
+- 模块路径：{module_path}
+- 技术栈：{detected_stack}
+
+## 输入文件（必须全部读取）
+- atool-analysis/modules/{module_name}/dev-guide.md — 当前内容（保留全部，在末尾追加）
+- atool-analysis/modules/{module_name}/prd.md — 精炼后的标准 PRD（8 节）
+- atool-analysis/modules/{module_name}/api.md — 接口定义
+- atool-analysis/modules/{module_name}/data-model.md — 数据模型（可能不存在，跳过）
+- atool-analysis/modules/{module_name}/README.md — 模块概述
+- .atool-docs/modules/{module_name}/data.json — 结构化数据（含 refine_hints）
+
+## 编码规范约束
+{conventions_context}
+
+## 精炼规则
+**必须读取并遵循**：`~/.claude/skills/software-architecture/SKILL.md` 中的 **Refine Mode（精炼模式）** 章节。该章节定义了标准的架构设计精炼流程和输出格式。按照其中的精炼规则逐条执行。
+
+补充说明（与 Refine Mode 保持一致）：
+- 在现有 dev-guide.md 内容末尾追加（不删除原有内容）
+- 追加 B-subset 组件设计（分层表 + 边界 + 依赖方向）
+- 追加 C-subset 数据与交互设计（数据所有权 + 同步/异步边界 + API 契约）
+- 追加至少 1 个 ADR（使用 7 节 ADR 模板：Status/Context/Decision/Options/Consequences/NFR Impact/Related）
+- NFR 对齐：标注 [待系统级确认]
+
+## 输出
+原地覆盖 atool-analysis/modules/{module_name}/dev-guide.md
+
+## 禁止行为
+- 不删除 dev-guide.md 的原有内容
+- 不修改 prd.md / api.md / data-model.md / README.md / test-cases.md
+- 不创建新文件
+- 不生成项目级文档（A/D/E/F）
+```
+
+完成后写入 checkpoint（使用唯一临时文件）：
+
+```bash
+TMP_FILE=".atool-docs/analysis-state.json.tmp.{module_name}.archrefine"
+jq --arg mod "{module_name}" \
+   '.refine_status[$mod].arch_refine = "completed"' \
+   .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
+```
+
+---
+
+#### Gate 3: 架构精炼门禁（Hard Gate）
+
+**对每个模块的精炼后 dev-guide.md 执行**：
+
+检查项：
+- 包含 "组件设计" 或 "Component Design" 章节标题（`grep -c "组件设计\|Component Design"`）
+- 包含 "ADR" 或 "架构决策" 标题（`grep -c "ADR\|架构决策"`）
+- ADR 中包含 "Status" + "Decision" + "Consequences"（或中文等价 "状态" + "决策" + "影响"）
+
+**通过** → 记录 `arch_gate = "passed"`
+**失败** → 同 Gate 2 的三选项恢复机制（A 重试 / B 手动 / C 降级）
+
+```bash
+# Gate 3 通过时写入（使用唯一临时文件）
+TMP_FILE=".atool-docs/analysis-state.json.tmp.{module_name}.gate3"
+jq --arg mod "{module_name}" \
+   '.refine_status[$mod].arch_gate = "passed"' \
+   .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
+```
+
+### 2.5.5 完成 Checkpoint
+
+每个模块完成全部精炼（或降级）后，写入完整状态（使用唯一临时文件）：
+
+```bash
+TMP_FILE=".atool-docs/analysis-state.json.tmp.{module_name}.final"
+jq --arg mod "{module_name}" \
+   --argjson score {prd_score} \
+   --arg conv "{conventions_skill}" \
+   '.refine_status[$mod] = {
+     "prd_refine": "completed",
+     "prd_coverage": $score,
+     "prd_gate": "passed",
+     "arch_refine": "completed",
+     "arch_gate": "passed",
+     "conventions_loaded": $conv,
+     "degraded": false,
+     "degraded_reason": null
+   }' .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
+```
+
+### 2.5.6 跨 IDE 降级
+
+| IDE | 检测方式 | 行为 |
+|-----|---------|------|
+| Claude Code | Agent tool 可用 | 完整并行（≤5 模块同时） |
+| Cursor | Agent tool 不可用 | 顺序执行（每次 1 个模块） |
+| Kiro | 无 Agent tool + 无 sub-agent | 跳过 Phase 2.5（与 Phase 2 一样） |
+
+检测逻辑沿用 SKILL.md 的 Cross-IDE Adaptation 章节。
+
+---
+
+## 完成条件
+
+- 所有非降级模块的 `refine_status.{name}.arch_gate == "passed"`
+- 降级模块已记录 `degraded = true` 和 `degraded_reason`
+- 更新 state：
+
+```bash
+jq '.phases.phase2_5_refine = "completed"' .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+```
+
+- 打印精炼摘要：
+
+```
+✅ Phase 2.5 REFINE 完成
+   精炼模块：{M}/{N}（{M} 个精炼完成，{D} 个降级）
+   平均 PRD 覆盖率：{avg_score}%
+   降级模块：{list}（如有，标注降级原因）
+```

package/skills/project-analyze/phases/phase3-graph.md

@@ -2,7 +2,13 @@
 
 **目标**：从 Phase 2 的 data.json 构建知识图谱 + 五维分析。全部通过 bash 库函数执行，禁止 AI 生成。
 
-**执行时间目标**：< 30秒
+**执行时间目标**：< 30秒（大型项目 < 60秒）
+
+**性能特点**：
+- Pure bash + jq（无 AI 开销）
+- 线性时间复杂度：O(M*E)，M=模块数，E=边数
+- 内存消耗：~50MB per 100 modules（jq slurp）
+- 中断保护：超过 120 秒自动停止，记录为 "failed"
 
 ## 前置检查
 

package/skills/project-analyze/phases/phase4-synthesize.md

@@ -1,57 +1,67 @@
-# Phase 4: SYNTHESIZE（主 Agent + Sub-Agents）
+# Phase 4: SYNTHESIZE（主 Agent — 聚合模式）
 
-**目标**：以模块文档 + 知识图谱为数据源，生成项目级交付物（overview/、quality/、diagrams/、project/）。
+**目标**：以 Phase 2.5 精炼后的模块文档 + 知识图谱为数据源，**聚合**为项目级交付物。Phase 4 不再从零生成模块级内容，而是聚合、补全项目级独有文档、并生成 PROJECT-DELIVERABLE.md 总览入口。
+
+---
+
+## IDE 适配（执行前检查）
+
+- **Claude Code**：主 Agent 单条线执行 Phase 4 逻辑（无额外并行）
+- **Cursor/其他**：同 Claude Code（Phase 4 本身是单 Agent，无 sub-agent 并行需求）
+
+**注**：Phase 4 与 Phase 2/4 不同，本身不使用 sub-agents，仅为单条线聚合逻辑，故无 IDE 差异。
+
+---
 
 ## 前置检查
 
 1. 确认 `phases.phase2_understand == "completed"`（必须）
-2. 检查 `phases.phase3_graph`：
+2. 检查 `phases.phase2_5_refine`（必须）：
+   - `"completed"` → 使用精炼后的 prd.md、dev-guide.md（含 ADR、架构设计）
+   - `"skipped"` 或 `"failed"` → **警告用户并询问是否继续**
+     - 若继续：使用 Phase 2 初稿（内容可能不完整）
+     - 若中止：建议用户重新执行 Phase 2.5
+3. 检查 `phases.phase3_graph`：
    - `"completed"` → 可使用图谱数据生成完整文档
    - `"failed"` → 跳过图谱相关输出（data-flow.mmd、module-dependencies.mmd），其余正常生成
 
 ## 输入数据
 
 - 模块文档（必须）：`atool-analysis/modules/*/README.md`
+- 模块精炼文档（必须）：`atool-analysis/modules/*/prd.md`、`dev-guide.md`、`test-cases.md`
 - 模块数据（必须）：`.atool-docs/modules/*/data.json`
 - 图谱数据（可选）：`.atool-docs/knowledge-graph.json`
 - 五维分析（可选）：`.atool-docs/multi-dimensional-analysis.json`
 
 ## 步骤
 
-### 4.1 生成项目概述（overview/）
-
-创建 `atool-analysis/overview/` 目录下 4 个文件：
+### 4.1 聚合项目概述（overview/）
 
-#### 4.1a `summary.md` — 业务摘要
+#### 4.1a summary.md（聚合）
 
-面向**非技术用户**。必须包含：
-1. **项目是做什么的**（2-4 句话，完全不用技术术语）
-2. **核心业务能力**（5-8 项，用业务语言描述）
-3. **关键数字**（模块数、接口数、核心实体数）
-4. **健康度摘要**（如存在严重技术债，用业务影响语言描述，如"某模块修改风险较高，可能影响XX功能稳定性"）
+从各模块 `README.md` 提取摘要，拼接为项目级概述：
+- 第 1 段：Executive Summary（CEO/VP 可读级别，3-5 句）
+- 第 2 段：模块清单表（模块名 / 职责 / 状态）
+- 第 3 段：技术栈概述（从 `analysis-state.json` 的 `detected_stack` 提取）
 
-**质量标准**：让产品经理读完能回答"系统能做什么"和"有什么主要风险"。
+#### 4.1b architecture.md（聚合 + 项目级补全）
 
-#### 4.1b `architecture.md` — 架构说明
+从各模块精炼后的 `dev-guide.md` 的架构章节聚合：
+1. **全局架构图**（Mermaid graph TB）：从各模块的组件设计章节提取模块名和依赖关系，生成项目级视图
+2. **各模块架构摘要**：每个模块一段（模块名 / 分层 / 关键 ADR）
+3. **ADR 汇总**：从各模块 dev-guide.md 提取所有 ADR，汇总为项目级 ADR 列表
+4. **项目级补全**（引用 software-architecture A/E/F 模板结构）：
+   - A. Architecture Summary：Business Context + Technical Drivers + Style Decision
+   - E. Risk and Trade-offs：项目级风险登记表
+   - F. Evolution Roadmap：分阶段演进表
 
-必须包含：
-1. **系统架构图**（Mermaid graph TB 格式，同时写入 `diagrams/architecture.mmd`）
-2. **各层/模块职责说明**
-3. **核心数据流**（用 Mermaid sequence diagram，同时写入 `diagrams/data-flow.mmd`）
-4. **关键设计决策**（ADR 格式：决策/选择/替代/理由）
+#### 4.1c tech-stack.md（保持不变）
 
-#### 4.1c `tech-stack.md` — 技术栈明细
+从 Phase 1 pre-scan 数据聚合，无需精炼。
 
-从 data.json 聚合：框架、语言版本、构建工具、主要依赖库、运行时环境。
+#### 4.1d getting-started.md（聚合）
 
-#### 4.1d `getting-started.md` — 新人上手指南
-
-**Zero-KT 标准**：新人仅凭此文档可完成：
-1. **环境搭建**（前置依赖 + 安装命令）
-2. **运行项目**（启动命令 + 验证成功的方式）
-3. **理解主要业务流程**（3-5 个核心场景 walkthrough）
-4. **添加第一个功能**（具体到哪个模块/文件/类，附代码模板）
-5. **运行测试**（命令 + 预期结果）
+从各模块 `dev-guide.md` 的快速启动部分聚合。
 
 ### 4.2 生成 Mermaid 图表（diagrams/）
 
@@ -120,49 +130,41 @@ Phase 3（1-3月）: {长期优化}
 #### 4.3c `recommendations.md`
 可行动的 Top 10 改进建议。每项包含：问题描述、建议行动、预期收益、工作量。
 
-### 4.4 生成项目级文档（project/）
-
-创建 `atool-analysis/project/` 目录下 4 个文件：
-
-#### 4.4a `project/prd.md` — 项目级 PRD（聚合视角）
+### 4.4 聚合项目级文档（project/）
 
-从所有模块的 prd.md 聚合，生成项目级视角：
+#### 4.4a project/prd.md（聚合）
 
-1. **Executive Summary**：项目整体业务定位（2-3 段，面向 CEO/VP 级别读者）
-2. **全局用户流**：跨模块的端到端用户旅程（Mermaid journey 格式，至少 3 个核心场景）
-3. **功能矩阵**：模块 × 功能的交叉表（哪个模块提供哪些功能）
-4. **非目标汇总**：整个项目明确不做的事
-5. **Phased Rollout**：MVP → v1.1 → v2.0 路线图建议（基于技术债和功能完成度推断）
+从各模块精炼后的 `prd.md` 聚合为项目级 PRD：
+1. **Executive Summary**：项目整体业务目标 + 成功标准
+2. **功能矩阵**：模块 × 功能 交叉表
+3. **NFR 汇总**：
+   - 从各模块 NFR-{MOD}-NNN 归纳生成 NFR-SYS-NNN（系统级）
+   - NFR-SYS-NNN 必须覆盖所有模块 NFR 的范围
+4. **全局用户流**：Mermaid journey 图
+5. **非目标汇总**：各模块非目标聚合
+6. **Phased Rollout Roadmap**
 
-**质量标准**：客户可直接使用此文档进行项目验收。
+#### 4.4b project/deployment.md（项目级独有）
 
-#### 4.4b `project/deployment.md` — 部署文档
+Phase 4 主 agent 直接引用 software-architecture D 模板结构生成（不启动 sub-agent）：
+- 部署拓扑（Mermaid）
+- 环境配置矩阵（dev/staging/prod）
+- CI/CD 流程
+- 可观测性表
+- 回滚策略
+- 扩缩容规则
 
-从代码中推断：
+#### 4.4c project/testing-strategy.md（聚合 + 项目级补全）
 
-1. **环境要求**：语言版本/运行时/数据库/中间件（从 package.json/pom.xml/go.mod 等提取）
-2. **配置项清单**：从 config/env 文件提取，格式：`| 变量名 | 类型 | 默认值 | 必填 | 说明 |`
-3. **启动命令**：dev/staging/production 三套（从 scripts/Makefile/docker-compose 提取）
-4. **Docker 配置**（如有 Dockerfile）：镜像构建 + 运行命令
-5. **部署检查清单**：10 项 checkbox（数据库迁移/配置注入/健康检查/日志/监控/回滚准备...）
-6. **回滚策略**：基于部署方式的回滚步骤
-7. **健康检查接口**：从代码中的 /health /ready /live 端点提取
+Phase 4 主 agent 聚合各模块 `test-cases.md` + 补全：
+- 模块级测试覆盖汇总
+- 集成测试策略
+- E2E 测试策略
+- 性能测试策略
 
-#### 4.4c `project/testing-strategy.md` — 测试策略
+#### 4.4d project/runbook.md（聚合）
 
-1. **测试金字塔**：单元:集成:E2E 比例建议（基于项目规模和技术栈）
-2. **覆盖率目标**：行覆盖/分支覆盖建议值
-3. **关键路径测试场景**：从 `project/prd.md` 核心用户流推导的 E2E 场景
-4. **自动化建议**：推荐测试框架 + 配置模板（基于技术栈，如 Jest/JUnit/pytest）
-5. **测试数据策略**：种子数据/工厂模式建议
-
-#### 4.4d `project/runbook.md` — 运维手册
-
-1. **常见故障排查**：`| 症状 | 可能原因 | 诊断命令 | 解决方案 |`（至少 5 个场景）
-2. **监控指标建议**：API 延迟/错误率/内存/CPU/数据库连接池
-3. **告警阈值建议**：每个指标的 warning/critical 阈值
-4. **日志查看**：日志文件路径 + 常用查询命令（grep/jq）
-5. **扩缩容指南**（如有容器化）
+Phase 4 主 agent 聚合各模块 `dev-guide.md` 的运维相关章节。
 
 ### 4.5 生成安全和性能文档（quality/ 扩展）
 
@@ -197,64 +199,59 @@ OWASP Top 10 逐项检查，从所有 data.json 的 `security_issues` 聚合：
 4. **并发处理**：线程池/连接池配置评估
 5. **建议优化点**：Top 5 性能改进建议（按预期收益排序，每项包含：问题/影响/建议/预期收益）
 
-### 4.6 更新 State
-
-> **执行命令（必须通过 Bash 工具）：**
-> ```bash
-> DOCS_DIR="$(pwd)/.atool-docs"
-> jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
->   '.phases.phase4_synthesize = "completed" | .updated_at = $ts' \
->   "$DOCS_DIR/analysis-state.json" > "$DOCS_DIR/analysis-state.json.tmp" \
->   && mv "$DOCS_DIR/analysis-state.json.tmp" "$DOCS_DIR/analysis-state.json"
-> echo "Phase 4 completed"
-> ```
-
-### 4.7 PRD 覆盖率检测
-
-在所有文档生成完成后，检查模块级 PRD 的覆盖率：
-
-**对每个 `atool-analysis/modules/{name}/prd.md`，检查是否包含以下关键要素**：
-1. 用户故事（As a... I want...）— 搜索 "As a" 或 "用户故事"
-2. 验收标准（AC-）— 搜索 "AC-" 或 "验收标准"
-3. 按钮/交互定义 — 搜索 "按钮" 或 "输入字段" 或 "交互"
-4. 字段校验规则 — 搜索 "校验" 或 "必填" 或 "validation"
-5. 四种状态 — 搜索 "加载中" 或 "空数据" 或 "错误状态"
-
-**覆盖率评分**：每个要素命中 = 20分，总分 0-100。
-
-将评分写入 `analysis-state.json`：
-```json
-"prd_coverage": {
-  "average_score": 60,
-  "modules_below_70": ["order-service", "payment-service"],
-  "recommendation": "建议运行 /requirements-writer 补齐 PRD 深度"
-}
-```
+### 4.6 NFR 一致性回扫
 
-**如果平均覆盖率 < 70%**，在 Phase 5 完成摘要中显示：
-```
-⚠️  PRD 覆盖率不足（{score}%）
-    以下模块的 PRD 缺少按钮级交互定义/验收标准/字段校验：
-    - order-service (40%)
-    - payment-service (60%)
-    
-    建议运行 /requirements-writer 生成正式交付级 PRD：
-    → requirements-writer 会读取本次分析结果，自动进入后向增强模式
-    → 通过 Multi-Agent 并行补齐每个模块的按钮级定义和覆盖率检查表
+在 `project/prd.md` 生成 NFR-SYS-NNN 后，对所有模块的 prd.md 执行回扫：
+
+1. 读取 `project/prd.md` 中的 NFR-SYS-NNN 列表
+2. 对每个 `modules/*/prd.md`：
+   - 将 `[待系统级确认]` 替换为 `(≤ NFR-SYS-NNN)`（匹配对应类别：性能→性能，安全→安全，可用性→可用性）
+   - 如果模块 NFR 数值超出系统 NFR 范围，标注 `[⚠️ 超出系统级约束 NFR-SYS-NNN]`
+3. 记录回扫结果到 `analysis-state.json`：`nfr_backscan.conflicts_count`
+
+### 4.7 架构违反率检测
+
+如果 `.atool-docs/knowledge-graph.json` 存在：
+
+```bash
+VIOLATIONS=$(jq '[.edges[] | select(.type == "layer_violation")] | length' .atool-docs/knowledge-graph.json)
+TOTAL=$(jq '.edges | length' .atool-docs/knowledge-graph.json)
 ```
 
+如果 `VIOLATIONS / TOTAL > 0.30`（>30%）：
+- 记录到 `analysis-state.json`：`arch_violation_rate`
+- 在 Phase 5 完成摘要中建议：`⚠️ 架构层违反率 {rate}%（>30%），建议运行 /software-architecture 进行深度架构审查`
+
+### 4.8 生成 PROJECT-DELIVERABLE.md
+
+生成 `atool-analysis/PROJECT-DELIVERABLE.md` 总览入口文件。
+
+结构（硬性）：
+
+1. **标题 + 元信息**：项目名、生成时间、分析深度、技术栈、模块数/精炼数/降级数
+2. **执行摘要**：3-5 段项目级业务概述（CEO/VP 可读）
+3. **文档导航**：
+   - 项目级文档表（PRD / 架构 / 部署 / 测试策略 / 运维手册，含相对链接）
+   - 模块级文档表（每个模块一行，含 PRD/架构/API/数据模型/测试用例链接 + 精炼状态 ✅/⚠️）
+   - 质量报告表（code-review / tech-debt / security-audit / performance-baseline）
+4. **全局架构概览**：从 `overview/architecture.md` 内联 Mermaid 图
+5. **功能矩阵**：从 `project/prd.md` 内联核心功能表
+6. **精炼覆盖率报告**：每个模块的 PRD 覆盖率 + 架构完整度 + 精炼状态（从 `analysis-state.json` 的 `refine_status` 读取）
+7. **后续操作建议**：降级模块补全 / code-review / project-query / software-architecture（如架构违反率 >30%）
+
 ## 完成条件
 
-- `atool-analysis/overview/summary.md` 存在
-- `atool-analysis/overview/architecture.md` 存在
-- `atool-analysis/overview/getting-started.md` 存在
-- `atool-analysis/diagrams/architecture.mmd` 存在
-- `atool-analysis/quality/code-review.md` 存在（含重构优先级矩阵 + 代码示例）
-- `atool-analysis/project/prd.md` 存在
-- `atool-analysis/project/deployment.md` 存在
-- `atool-analysis/project/testing-strategy.md` 存在
-- `atool-analysis/project/runbook.md` 存在
-- `atool-analysis/quality/security-audit.md` 存在
-- `atool-analysis/quality/performance-baseline.md` 存在
-- PRD 覆盖率检测已执行（结果写入 state.json）
-- `phases.phase4_synthesize = "completed"`
+- `overview/summary.md` 存在
+- `overview/architecture.md` 存在且包含 Mermaid 图
+- `project/prd.md` 存在且包含 NFR-SYS
+- `project/deployment.md` 存在
+- `project/testing-strategy.md` 存在
+- `project/runbook.md` 存在
+- `PROJECT-DELIVERABLE.md` 存在且包含所有模块链接
+- NFR 一致性回扫已执行
+- 更新 state：
+
+```bash
+jq '.phases.phase4_synthesize = "completed" | .deliverable_status.project_deliverable_md = "completed"' \
+   .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+```