@dtt_siye/atool 1.3.1 → 1.4.0

package/skills/architecture-guard/rules/violation-detection.md

@@ -0,0 +1,90 @@
+# Architecture Violation Detection Rules
+
+## Dependency Direction Rules
+
+### Rule 1: Strict Layer Ordering
+Each layer may only depend on layers below it in the hierarchy. A dependency pointing upward is a violation.
+
+```
+ALLOWED: Presentation → Application → Domain → Infrastructure
+VIOLATION: Domain → Application (upward dependency)
+VIOLATION: Infrastructure → Domain (skipping layers or upward)
+```
+
+### Rule 2: No Cross-Skip Dependencies
+A layer may not skip intermediate layers unless the intermediate layer has no relevant abstraction.
+
+```
+ALLOWED: Controller → Repository (if Service is just a pass-through)
+VIOLATION: Page → API (skipping Service layer with business logic)
+```
+
+## API Boundary Rules
+
+### Rule 3: No DTO Leakage
+Response/DTO/ViewModel types must NOT appear in Service or Repository layers.
+
+```
+VIOLATION: PaymentService.java imports OrderResponse
+VIOLATION: UserRepository.java returns UserDTO instead of UserEntity
+```
+
+### Rule 4: No Domain Logic in Presentation
+Business logic must NOT appear in Controller/Handler/Page layers.
+
+```
+VIOLATION: UserController.java contains validation logic (should be in Service)
+VIOLATION: OrderPage.vue contains price calculation (should be in Service)
+```
+
+## Circular Dependency Rules
+
+### Rule 5: No Import Cycles
+No circular import chains are allowed between modules.
+
+```
+VIOLATION: A imports B, B imports C, C imports A
+ALLOWED: A imports B, A imports C, B imports C (DAG)
+```
+
+### Rule 6: No Mutual Dependencies
+Two modules must not directly import from each other.
+
+```
+VIOLATION: UserService imports OrderService, OrderService imports UserService
+FIX: Extract shared logic into a third module or use events
+```
+
+## Module Boundary Rules
+
+### Rule 7: Bounded Context Isolation
+Modules from different bounded contexts should not directly import each other's internal types.
+
+```
+VIOLATION: billing/internal/invoice.go imports shipping/internal/package.go
+ALLOWED: billing/invoice.go imports shipping/api.go (public API)
+```
+
+### Rule 8: No God Modules
+A module importing from more than 50% of other modules may be a god module.
+
+```
+WARNING: CommonUtils imports from 15 out of 20 modules
+FIX: Split into focused utility modules
+```
+
+## Detection Priority
+
+1. **Critical** (blocks commit): Circular dependencies, reverse dependencies
+2. **Warning** (should fix): API boundary leaks, cross-module imports
+3. **Info** (consider): God modules, new unknown modules
+
+## Output Format
+
+Each violation includes:
+- `file`: The file containing the violation
+- `line`: Line number of the problematic import/usage
+- `rule`: Which rule was violated (1-8)
+- `severity`: Critical / Warning / Info
+- `detail`: Human-readable explanation
+- `suggestion`: How to fix

package/skills/ci-feedback/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: ci-feedback
+description: "Use after modifying source files to run local build/test and get automated feedback. 在修改源码后使用 — 运行本地构建/测试获取自动化反馈，失败时自动进入调试流程."
+version: 0.1.0
+category: quality
+---
+
+# CI Feedback — Local Build & Test Automation
+
+Automatically runs project build and test commands, parses results, and feeds them back into the AI workflow. Creates a tight feedback loop without requiring CI/CD infrastructure.
+
+## When to Use
+
+- After modifying source files (auto-suggested by doc-sync-reminder or task-state-tracker)
+- Before claiming a task complete (invoked by verification-before-completion)
+- When the user says "run the tests" or "check if it builds"
+- When debugging (auto-triggered by systematic-debugging after fix attempts)
+
+## How It Works
+
+### Step 1: Detect Build Commands
+
+Read build/test commands from the project's CLAUDE.md `## Build & Run` section. If not found, auto-detect from project files:
+
+| Project File | Build Command | Test Command |
+|-------------|---------------|--------------|
+| `pom.xml` | `mvn compile -q` | `mvn test -q` |
+| `build.gradle` / `build.gradle.kts` | `gradle compileJava` | `gradle test` |
+| `package.json` | `npm run build` | `npm test` |
+| `Cargo.toml` | `cargo build` | `cargo test` |
+| `go.mod` | `go build ./...` | `go test ./...` |
+| `pyproject.toml` / `setup.py` | `python -m compileall .` | `pytest` |
+| `pubspec.yaml` | `flutter build` | `flutter test` |
+| `Makefile` | `make build` | `make test` |
+
+### Step 2: Run Build
+
+Execute the build command and capture:
+- Exit code (0 = success)
+- stdout (warnings)
+- stderr (errors)
+
+```
+Build Result:
+- Status: PASS / FAIL
+- Duration: {time}
+- Warnings: {count} (list if < 10)
+- Errors: {count} (list all)
+```
+
+If build FAILS → go to Step 4 (Auto-debug).
+
+### Step 3: Run Tests
+
+Execute the test command and capture:
+- Exit code
+- Test summary (passed/failed/skipped)
+- Specific failure details
+
+```
+Test Result:
+- Status: PASS / FAIL
+- Tests: {passed} passed, {failed} failed, {skipped} skipped
+- Duration: {time}
+- Failures:
+  - {test_name}: {error_message} (file:line)
+```
+
+If tests FAIL → go to Step 4 (Auto-debug).
+
+### Step 4: Auto-debug on Failure
+
+When build or tests fail:
+
+1. **Parse the error output** — extract file paths, line numbers, error messages
+2. **Classify the error**:
+   - Compilation error → syntax/type mismatch
+   - Test assertion → logic error
+   - Missing dependency → configuration error
+   - Timeout → performance issue
+3. **Invoke /systematic-debugging workflow**:
+   - Identify root cause (NOT symptoms)
+   - Propose targeted fix
+   - Re-run only the failed tests (if possible)
+4. **Track in task-state.json**:
+   ```json
+   {
+     "last_build_status": "FAIL",
+     "last_build_errors": 2,
+     "auto_debug_attempts": 1,
+     "pending_actions": ["fix_build_error", "update_docs"]
+   }
+   ```
+
+### Step 5: Update Task State
+
+On success, update `.claude/task-state.json`:
+```json
+{
+  "verification_passed": true,
+  "last_build_status": "PASS",
+  "last_test_status": "PASS",
+  "pending_actions": ["update_docs"]
+}
+```
+
+On failure, the state tracks retry attempts and remaining errors.
+
+## Integration Points
+
+### With task-state-tracker
+Reads `.claude/task-state.json` to know which files were modified, then runs targeted tests if the framework supports it.
+
+### With verification-before-completion
+`/verification-before-completion` invokes ci-feedback as part of its gate check: "tests pass" is a hard requirement.
+
+### With systematic-debugging
+On build/test failure, automatically enters the systematic-debugging workflow rather than blindly retrying.
+
+### With architecture-guard
+After a successful build, optionally runs architecture-guard to check for structural violations.
+
+## Output Format
+
+```
+## CI Feedback Report
+
+### Build
+| Metric | Value |
+|--------|-------|
+| Status | PASS |
+| Duration | 3.2s |
+| Warnings | 1 (unused import in UserService.java) |
+
+### Tests
+| Metric | Value |
+|--------|-------|
+| Status | PASS |
+| Total | 47 |
+| Passed | 47 |
+| Failed | 0 |
+| Duration | 12.5s |
+
+### Summary
+All checks passed. Task state updated.
+Remaining: update docs before completion.
+```
+
+## Retry Strategy
+
+When auto-debugging:
+1. Fix the identified root cause
+2. Re-run ONLY the failing tests (if framework supports file-specific tests)
+3. If fix introduces new failures → stop and report to user
+4. Maximum 3 auto-debug cycles before escalating to user
+
+## Skill 协作
+
+| 协作 Skill | 触发条件 | 交互方式 |
+|-----------|---------|---------|
+| verification-before-completion | Before claiming done | 作为验证步骤执行构建+测试 |
+| systematic-debugging | Build/test failure | 自动进入调试流程 |
+| task-state-tracker | State file available | 读取修改文件列表，更新验证状态 |
+| architecture-guard | Build success | 可选执行架构检查 |
+| {stack}-conventions | Test framework detection | 使用栈级测试命令 |

package/skills/project-analyze/SKILL.md

@@ -94,7 +94,10 @@ Phase 5: EXPORT     → phases/phase5-export.md       (bash + AI, export 单文
 4. **Phase 2 并发上限 5 个 sub-agent**，超出部分按 importance 降序分批排队
 5. **Phase 3 bash 调用失败时**：在 state.json 记录 `phase3_graph: "failed"`，继续 Phase 4（跳过图谱相关文档，Phase 4 检查此标记）
 6. **断点续传**：先读 state.json，跳过 `status: "completed"` 的 phase
-7. Phase 2.5 在 Phase 2 完成后自动执行；`--skip-refine` 可跳过；`--refine-threshold N` 自定义门禁阈值（默认 70）
+7. **Phase 2.5 参数识别**（无需 bash 解析，直接在用户消息中匹配）：
+   - `--skip-refine`：用户消息中包含此字符串 → Phase 2.5 标记为 "skipped"，跳过精炼链，直进 Phase 3
+   - `--refine-threshold N`：用户消息中包含此模式 → 提取 N 作为 Gate 1/2/3 门禁阈值（默认 70）
+   - 例：用户说"分析项目 --skip-refine"→ 立即检测到 --skip-refine 字符串，跳过 Phase 2.5
 
 ### 状态管理（简化版）
 
@@ -103,7 +106,8 @@ Phase 5: EXPORT     → phases/phase5-export.md       (bash + AI, export 单文
 {
   "version": "5.2.0",
   "project": "...",
-  "detected_stack": "java-spring",
+  "project_root": "...",
+  "stack": "java-spring",
   "depth": "L2",
   "phases": {
     "phase1_setup": "completed",
@@ -194,16 +198,56 @@ state.checkpoint = { last_completed_phase, last_completed_module, next_pending_m
 write analysis-state.json
 ```
 
-### Resume Flow
-1. Read `.atool-docs/analysis-state.json`
-2. If no state file → full analysis
-3. If `phases.phase1_setup != "completed"` → execute Phase 1
-4. Detect stale modules (file hash mismatch) → mark for re-analysis
-5. Determine resume point from checkpoint
-6. Execute pending phases, skip completed, rerun stale
-7. Update final state
+### Resume Flow（断点恢复决策树）
 
-Detailed resume logic: see `phases/phase1-setup.md`.
+**入口**：执行 Phase 1 setup 时自动检测恢复状态
+
+```
+1. 读取 .atool-docs/analysis-state.json（若不存在）
+   └─ 启动全新分析（fresh start）
+
+2. 存在 state.json
+   ├─ phases.phase1_setup != "completed"
+   │  └─ 执行 Phase 1（重新检测栈 / manifest / importance）
+   │
+   ├─ phases.phase1_setup == "completed"
+   │  ├─ 检查 phase2_understand 状态
+   │  │  ├─ "pending" → 执行 Phase 2（全部模块）
+   │  │  ├─ "in_progress" → 恢复到 Phase 2 中断位置（读 state.module_status，跳过已完成）
+   │  │  └─ "completed" → 进入 Phase 2.5
+   │  │
+   │  ├─ 检查 phase2_5_refine 状态
+   │  │  ├─ "pending" / "failed" → 执行 Phase 2.5（全部模块）
+   │  │  ├─ "in_progress" → 恢复精炼进度（读 state.refine_status，跳过已通过 Gate 3）
+   │  │  └─ "completed" / "skipped" → 进入 Phase 3
+   │  │
+   │  ├─ 检查 phase3_graph 状态
+   │  │  ├─ "pending" → 执行 Phase 3（知识图谱生成）
+   │  │  ├─ "in_progress" / "failed" → 重新执行 Phase 3
+   │  │  └─ "completed" → 进入 Phase 4
+   │  │
+   │  ├─ 检查 phase4_synthesize 状态
+   │  │  ├─ "pending" → 执行 Phase 4（聚合合成）
+   │  │  ├─ "in_progress" / "failed" → 重新执行 Phase 4
+   │  │  └─ "completed" → 进入 Phase 5
+   │  │
+   │  └─ 检查 phase5_export 状态
+   │     ├─ "pending" → 执行 Phase 5（最终导出）
+   │     ├─ "in_progress" / "failed" → 重新执行 Phase 5
+   │     └─ "completed" → 分析完成（可选重新导出）
+```
+
+**断点恢复的具体判断**（在每个 Phase 入口执行）：
+- 若 phase 状态为 "completed" 且无 `--force`，**跳过该 phase**
+- 若 phase 状态为 "in_progress"/"failed"，**重新执行该 phase**（覆盖部分输出）
+- 若 phase 状态为 "pending"，**首次执行该 phase**
+
+**文件变更检测**（Phase 2+ 的可选优化）：
+- 计算 project root 下所有源文件的 hash（与 manifest.json 对比）
+- 若有新增/删除/修改的文件，标记对应模块为"需重新分析"
+- 该模块在 Phase 2 中重新派发 sub-agent（即使之前已完成）
+
+详见各 Phase 的前置检查条款（phase1-setup.md → phase5-export.md）
 
 ### Incremental Document Recovery
 When resuming Phase 5, incrementally update already-generated documents using `<!-- aTool-module-start:{slug} -->` markers. Only regenerate changed modules.
@@ -274,6 +318,51 @@ When resuming Phase 5, incrementally update already-generated documents using `<
 
 ---
 
+## 调试指南（Debug Guide）
+
+### 查看当前分析状态
+```bash
+cat .atool-docs/analysis-state.json | jq '.phases'
+# 输出每个 Phase 的状态（completed/in_progress/failed/pending）
+```
+
+### 强制重新执行某个 Phase
+```bash
+# 删除特定 Phase 的状态
+jq '.phases.{phase_name} = "pending"' .atool-docs/analysis-state.json > .tmp && mv .tmp .atool-docs/analysis-state.json
+
+# 示例：重新执行 Phase 2
+jq '.phases.phase2_understand = "pending"' .atool-docs/analysis-state.json > .tmp && mv .tmp .atool-docs/analysis-state.json
+
+# 重新触发分析
+# 在对话中说：分析项目 （AI 会检测到 phase2_understand = "pending"，重新执行）
+```
+
+### 完全重置分析（回到 Phase 1）
+```bash
+rm -rf .atool-docs/
+# 重新触发分析会从 Phase 1 开始
+```
+
+### 查看模块分析进度
+```bash
+# 查看每个模块在 Phase 2 的状态
+jq '.module_status' .atool-docs/analysis-state.json
+
+# 查看 Phase 2.5 精炼进度
+jq '.refine_status' .atool-docs/analysis-state.json
+```
+
+### 诊断常见问题
+| 问题 | 诊断命令 | 解决方案 |
+|------|---------|---------|
+| 没有检测到模块 | `cat .atool-docs/pre-scan/manifest.json \| jq '.modules'` | 检查源文件格式或 detect-stack 规则 |
+| phase3_graph 失败 | `cat .atool-docs/analysis-state.json \| jq '.phases.phase3_graph'` | 运行 `source lib/knowledge-graph.sh; assemble_enhanced_graph` 检查错误 |
+| Sub-agent 无法读文件 | `cat .atool-docs/modules/{name}/data.json` | 检查 Phase 2 初稿是否生成 |
+| 精炼 Gate 失败 | `cat atool-analysis/modules/{name}/prd.md \| wc -l` | PRD 文件小于 30 行，需要扩展初稿 |
+
+---
+
 ## Important Notes
 
 - Always check `.atool-docs/` before starting; offer incremental update if exists

package/skills/project-analyze/phases/phase1-setup.md

@@ -155,7 +155,8 @@
 >
 > cat > "$DOCS_DIR/analysis-state.json" << STATEEOF
 > {
->   "version": "5.1",
+>   "version": "5.2.0",
+>   "project": "$(basename "$PROJECT_ROOT")",
 >   "project_root": "$PROJECT_ROOT",
 >   "stack": "$STACK",
 >   "depth": "$DEPTH",
@@ -164,11 +165,14 @@
 >   "phases": {
 >     "phase1_setup": "completed",
 >     "phase2_understand": "pending",
+>     "phase2_5_refine": "pending",
 >     "phase3_graph": "pending",
 >     "phase4_synthesize": "pending",
 >     "phase5_export": "pending"
 >   },
 >   "module_status": $MODULE_STATUS,
+>   "refine_status": {},
+>   "deliverable_status": {},
 >   "updated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 > }
 > STATEEOF
@@ -180,3 +184,13 @@
 - `.atool-docs/pre-scan/manifest.json` 存在（或 warning 已记录）
 - `.atool-docs/analysis-state.json` 已写入且 `phases.phase1_setup = "completed"`
 - 用户已确认分析深度
+
+## 故障排查（Troubleshooting）
+
+| 症状 | 可能原因 | 解决方案 |
+|------|---------|---------|
+| pre-scan 超时（>2分钟） | 项目过大或网络配置问题 | 检查 PROJECT_ROOT，尝试指定具体子目录 |
+| manifest.json 为空或缺数据 | 源文件识别失败 | 检查 PRESCAN_EXCLUDE_DIRS，确保源文件扩展名被识别 |
+| state.json 初始化失败 | 目录权限问题 | 确保 ~/.atool-docs 目录可写 |
+| detected_stack = "generic" | 技术栈检测失败 | 检查是否存在 package.json/pom.xml/go.mod 等 |
+| 重复执行 Phase 1 | 上次中断或状态不清 | `rm -rf .atool-docs/analysis-state.json` 后重试 |

package/skills/project-analyze/phases/phase2-understand.md

@@ -2,7 +2,16 @@
 
 **目标**：每个模块派发 1 个 sub-agent，产出三层文档（业务/技术/数据），直接写入 `atool-analysis/modules/`。
 
-**并发上限：5 个 sub-agent**
+---
+
+## IDE 适配（执行前检查）
+
+- **Claude Code**：使用 Agent 工具批量派发，每批最多 5 个并行，等待全部完成后派发下一批
+- **Cursor/其他**：**顺序执行**，按 importance 降序逐模块处理，每个模块完成后更新 state.json
+  - *原因*：Cursor 不支持并行 sub-agent，自动降级为逐个执行
+  - *判断方式*：若 Agent 工具不可用或不响应，自动切换到顺序模式
+
+---
 
 ## 前置检查
 

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

@@ -9,7 +9,7 @@
 ## 前置检查
 
 1. `analysis-state.json` 中 `phases.phase2_understand == "completed"`
-2. 读取 `detected_stack` 用于 conventions 加载
+2. 读取 `stack` 用于 conventions 加载
 3. 如果 `phases.phase2_5_refine == "completed"` 且非 `--force`，跳过本 Phase
 4. 如果 `--skip-refine`，跳过本 Phase
 
@@ -27,7 +27,7 @@
 
 ```bash
 # 从 state.json 读取技术栈
-STACK=$(jq -r '.detected_stack // "generic"' .atool-docs/analysis-state.json)
+STACK=$(jq -r '.stack // "generic"' .atool-docs/analysis-state.json)
 ```
 
 从对应 conventions SKILL.md 中提取以下章节内容（不加载全文，控制在 ~200 行）：
@@ -94,11 +94,13 @@ MODULES=$(jq -r '.modules | sort_by(-.importance) | .[].name' .atool-docs/pre-sc
 {conventions_context}
 
 ## 精炼规则
-参考 requirements-writer SKILL.md 的 "Refine Mode（精炼模式）" 章节，严格按照其中的精炼逻辑执行：
-1. 保留初稿 §1-§3 和原 §4 非目标（移至 §6）
-2. 补全 §4 数据需求、§5 跨模块依赖、§7 风险与假设、§8 需求追溯矩阵
-3. 增强 §2 加 FR-{MOD}-NNN 编号 + Given-When-Then AC + UI 交互表；§3 加 NFR-{MOD}-NNN 编号，标注 [待系统级确认]
-4. 输出必须包含完整 8 节结构
+**必须读取并遵循**：`~/.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
@@ -109,12 +111,13 @@ MODULES=$(jq -r '.modules | sort_by(-.importance) | .[].name' .atool-docs/pre-sc
 - 不创建新文件
 ```
 
-完成后立即写入 checkpoint：
+完成后立即写入 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 && mv tmp .atool-docs/analysis-state.json
+   .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
 ```
 
 ---
@@ -151,10 +154,11 @@ jq --arg mod "{module_name}" \
 选择 C 时：`refine_status.{name}.degraded = true, degraded_reason = "PRD coverage {score}% below threshold"`
 
 ```bash
-# Gate 2 通过时写入
+# 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 && mv tmp .atool-docs/analysis-state.json
+   .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
 ```
 
 ---
@@ -186,12 +190,14 @@ jq --arg mod "{module_name}" --argjson score {score} \
 {conventions_context}
 
 ## 精炼规则
-参考 software-architecture SKILL.md 的 "Refine Mode（精炼模式）" 章节，严格按照其中的精炼逻辑执行：
-1. 在现有 dev-guide.md 内容末尾追加（不删除原有内容）
-2. 追加 B-subset 组件设计（分层表 + 边界 + 依赖方向）
-3. 追加 C-subset 数据与交互设计（数据所有权 + 同步/异步边界 + API 契约）
-4. 追加至少 1 个 ADR（使用 7 节 ADR 模板：Status/Context/Decision/Options/Consequences/NFR Impact/Related）
-5. NFR 对齐：标注 [待系统级确认]
+**必须读取并遵循**：`~/.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
@@ -203,12 +209,13 @@ jq --arg mod "{module_name}" --argjson score {score} \
 - 不生成项目级文档（A/D/E/F）
 ```
 
-完成后写入 checkpoint：
+完成后写入 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 && mv tmp .atool-docs/analysis-state.json
+   .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
 ```
 
 ---
@@ -226,17 +233,19 @@ jq --arg mod "{module_name}" \
 **失败** → 同 Gate 2 的三选项恢复机制（A 重试 / B 手动 / C 降级）
 
 ```bash
-# Gate 3 通过时写入
+# 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 && mv tmp .atool-docs/analysis-state.json
+   .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}" \
@@ -249,7 +258,7 @@ jq --arg mod "{module_name}" \
      "conventions_loaded": $conv,
      "degraded": false,
      "degraded_reason": null
-   }' .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+   }' .atool-docs/analysis-state.json > "$TMP_FILE" && mv "$TMP_FILE" .atool-docs/analysis-state.json
 ```
 
 ### 2.5.6 跨 IDE 降级

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

@@ -2,10 +2,26 @@
 
 **目标**：以 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），其余正常生成