@haaaiawd/anws 1.0.1 → 1.2.0

package/lib/init.js

@@ -2,6 +2,7 @@
 
 const fs = require('node:fs/promises');
 const path = require('node:path');
+const crypto = require('node:crypto');
 const { copyDir } = require('./copy');
 const { MANAGED_FILES, USER_PROTECTED_FILES } = require('./manifest');
 const { success, warn, info, fileLine, skippedLine, blank, logo } = require('./output');
@@ -25,6 +26,7 @@ async function init() {
     }
     // 仅覆盖托管文件（用户自有文件不受影响）
     const { written: updated, skipped } = await overwriteManaged(srcRoot, cwd);
+    await storeAgentsTemplateHash(srcRoot, cwd);
     printSummary(updated, skipped, 'updated');
     return;
   }
@@ -36,6 +38,9 @@ async function init() {
 
   const written = await copyDir(srcRoot, destRoot);
 
+  // 存储 agents.md 模板指纹，供后续 update 检测模板变化
+  await storeAgentsTemplateHash(srcRoot, cwd);
+
   // 打印文件列表
   for (const absPath of written) {
     const rel = path.relative(cwd, absPath).replace(/\\/g, '/');
@@ -159,4 +164,23 @@ function printNextSteps() {
   info('  2. Run /genesis in your AI assistant to start a new project');
 }
 
+/**
+ * 存储 agents.md 模板的 MD5 指纹。
+ * 供 `anws update` 检测模板是否在版本间发生了变化。
+ * @param {string} srcRoot  模板 .agent/ 目录绝对路径
+ * @param {string} cwd      项目根目录
+ */
+async function storeAgentsTemplateHash(srcRoot, cwd) {
+  const templatePath = path.join(srcRoot, 'rules', 'agents.md');
+  const hashPath = path.join(cwd, '.agent', 'rules', '.agents-template-hash');
+
+  try {
+    const content = await fs.readFile(templatePath, 'utf-8');
+    const hash = crypto.createHash('md5').update(content).digest('hex');
+    await fs.writeFile(hashPath, hash, 'utf-8');
+  } catch {
+    // 模板文件不存在时静默失败（不应该发生）
+  }
+}
+
 module.exports = init;

package/lib/update.js

@@ -2,6 +2,7 @@
 
 const fs = require('node:fs/promises');
 const path = require('node:path');
+const crypto = require('node:crypto');
 const { MANAGED_FILES, USER_PROTECTED_FILES } = require('./manifest');
 const { success, warn, error, info, fileLine, skippedLine, blank, logo } = require('./output');
 
@@ -66,10 +67,24 @@ async function update() {
       skippedLine(rel.replace(/\\/g, '/'));
     }
   }
+
+  // 检查 agents.md 模板是否有变更，提供 .new 文件供用户合并
+  const agentsMerged = await checkAgentsTemplate(cwd, srcRoot);
+
   blank();
   success(`Done! ${updated.length} file(s) updated${skipped.length > 0 ? `, ${skipped.length} skipped` : ''}.`);
   info('Managed files have been updated to the latest version.');
   info('Your custom files in .agent/ were not touched.');
+
+  if (agentsMerged) {
+    blank();
+    warn('agents.md template has changed!');
+    info('A new template has been saved to:');
+    info('  .agent/rules/agents.md.new');
+    blank();
+    info('Please review and merge the changes into your agents.md.');
+    info('After merging, delete agents.md.new.');
+  }
 }
 
 /**
@@ -95,4 +110,44 @@ async function askUpdate() {
   });
 }
 
+/**
+ * 检查 agents.md 模板是否相比上次安装/更新有变化。
+ * 用 hash 文件记录上次模板指纹，与新模板比较。
+ * 如果有变化 → 写入 agents.md.new + 更新 hash。
+ *
+ * @param {string} cwd       项目根目录
+ * @param {string} srcRoot   模板 .agent/ 目录
+ * @returns {Promise<boolean>} 是否产生了 .new 文件
+ */
+async function checkAgentsTemplate(cwd, srcRoot) {
+  const templatePath = path.join(path.dirname(srcRoot), '.agent', 'rules', 'agents.md');
+  const hashPath = path.join(cwd, '.agent', 'rules', '.agents-template-hash');
+  const newPath = path.join(cwd, '.agent', 'rules', 'agents.md.new');
+
+  const templateExists = await fs.access(templatePath).then(() => true).catch(() => false);
+  if (!templateExists) return false;
+
+  const templateContent = await fs.readFile(templatePath, 'utf-8');
+  const newHash = crypto.createHash('md5').update(templateContent).digest('hex');
+
+  // 读取上次存储的 hash
+  let oldHash = null;
+  try {
+    oldHash = (await fs.readFile(hashPath, 'utf-8')).trim();
+  } catch {
+    // hash 文件不存在（首次 update 或旧版本安装）
+  }
+
+  if (oldHash === newHash) {
+    return false; // 模板没变化
+  }
+
+  // 模板有变化 → 写入 .new 供用户合并
+  await fs.writeFile(newPath, templateContent, 'utf-8');
+  // 更新 hash 记录
+  await fs.writeFile(hashPath, newHash, 'utf-8');
+
+  return true;
+}
+
 module.exports = update;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haaaiawd/anws",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Antigravity Workflow System CLI — one command to install AI collaboration workflows into your project",
   "keywords": [
     "ai",

package/templates/.agent/rules/agents.md

@@ -1,90 +1,112 @@
-# AGENTS.md - AI 协作协议
-
-> **"如果你正在阅读此文档，你就是那个智能体 (The Intelligence)。"**
-> 
-> 这个文件是你的**锚点 (Anchor)**。它定义了项目的法则、领地的地图，以及记忆协议。
-> 当你唤醒（开始新会话）时，**请首先阅读此文件**。
-
----
-
-## 🧠 30秒恢复协议 (Quick Recovery)
-
-**当你开始新会话或感到"迷失"时，立即执行**:
-
-1. **读取 .agent/rules/agents.md** → 获取项目地图
-2. **查看下方"当前状态"** → 找到最新架构版本
-3. **读取 `genesis/v{N}/05_TASKS.md`** → 了解当前待办
-4. **开始工作**
-
----
-
-## 🗺️ 地图 (领地感知)
-
-以下是这个项目的组织方式：
-
-| 路径 | 描述 | 访问协议 |
-|------|------|----------|
-| `src/` | **实现层**。实际的代码库。 | 通过 Task 读/写。 |
-| `genesis/` | **设计演进史**。版本化架构状态 (v1, v2...)。 | **只读**(旧版) / **写一次**(新版)。 |
-| `genesis/v{N}/` | **当前真理**。最新的架构定义。 | 永远寻找最大的 `v{N}`。 |
-| `.agent/workflows/` | **工作流**。`/genesis`, `/blueprint` 等。 | 通过 `view_file` 阅读。 |
-| `.agent/skills/` | **技能库**。原子能力。 | 通过 `view_file` 调用。 |
-
----
-
-## 📍 当前状态 (由 Workflow 自动更新)
-
-> **注意**: 此部分由 `/genesis` 和 `/blueprint` 自动维护。
-
-- **最新架构版本**: `尚未初始化`
-- **活动任务清单**: `尚未生成`
-- **待办任务数**: -
-- **最近一次更新**: `-`
-
----
-
-## 🌳 项目结构 (Project Tree)
-
-> **注意**: 此部分由 `/genesis` 维护。
-
-```text
-(等待 Genesis 初始化结构树...)
-```
-
----
-
-## 🧭 导航指南 (Navigation Guide)
-
-> **注意**: 此部分由 `/genesis` 维护。
-
-- **在新架构就绪前**: 请勿大规模修改代码。
-- **遇到架构问题**: 请查阅 `genesis/v{N}/03_ADR/`。
-
----
-
-## 🛠️ 工作流注册表
-
-| 工作流 | 触发时机 | 产出 |
-|--------|---------|------|
-| `/genesis` | 新项目 / 重大重构 | PRD, Architecture, ADRs |
-| `/scout` | 变更前 / 接手项目 | `genesis/v{N}/00_SCOUT_REPORT.md` |
-| `/design-system` | genesis 后 | 04_SYSTEM_DESIGN/*.md |
-| `/blueprint` | genesis 后 | 05_TASKS.md |
-| `/forge` | blueprint 后 | 实际代码实现 |
-| `/change` | 微调已有任务 | 更新 TASKS + SYSTEM_DESIGN (仅修改) + CHANGELOG |
-| `/explore` | 调研时 | 探索报告 |
-| `/challenge` | 决策前质疑 | 07_CHALLENGE_REPORT.md |
-| `/craft` | 创建工作流/技能/提示词 | Workflow / Skill / Prompt 文档 |
-
----
-
-## 📜 宪法 (The Constitution)
-
-1. **版本即法律**: 不"修补"架构文档，只"演进"。变更必须创建新版本。
-2. **显式上下文**: 决策写入 ADR，不留在"聊天记忆"里。
-3. **交叉验证**: 编码前对照 `05_TASKS.md`。我在做计划好的事吗？
-4. **美学**: 文档应该是美的。善用 Markdown 和 Emoji。
-
----
-
-> **状态自检**: 准备好了？运行 `/genesis` 开始你的第一个项目设计吧。
+# AGENTS.md - AI 协作协议
+
+> **"如果你正在阅读此文档，你就是那个智能体 (The Intelligence)。"**
+> 
+> 这个文件是你的**锚点 (Anchor)**。它定义了项目的法则、领地的地图，以及记忆协议。
+> 当你唤醒（开始新会话）时，**请首先阅读此文件**。
+
+---
+
+## 🧠 30秒恢复协议 (Quick Recovery)
+
+**当你开始新会话或感到"迷失"时，立即执行**:
+
+1. **读取 .agent/rules/agents.md** → 获取项目地图
+2. **查看下方"当前状态"** → 找到最新架构版本
+3. **读取 `genesis/v{N}/05_TASKS.md`** → 了解当前待办
+4. **开始工作**
+
+---
+
+## 🗺️ 地图 (领地感知)
+
+以下是这个项目的组织方式：
+
+| 路径 | 描述 | 访问协议 |
+|------|------|----------|
+| `src/` | **实现层**。实际的代码库。 | 通过 Task 读/写。 |
+| `genesis/` | **设计演进史**。版本化架构状态 (v1, v2...)。 | **只读**(旧版) / **写一次**(新版)。 |
+| `genesis/v{N}/` | **当前真理**。最新的架构定义。 | 永远寻找最大的 `v{N}`。 |
+| `.agent/workflows/` | **工作流**。`/genesis`, `/blueprint` 等。 | 通过 `view_file` 阅读。 |
+| `.agent/skills/` | **技能库**。原子能力。 | 通过 `view_file` 调用。 |
+
+---
+
+## 📍 当前状态 (由 Workflow 自动更新)
+
+> **注意**: 此部分由 `/genesis`、`/blueprint` 和 `/forge` 自动维护。
+
+- **最新架构版本**: `尚未初始化`
+- **活动任务清单**: `尚未生成`
+- **待办任务数**: -
+- **最近一次更新**: `-`
+
+### 🌊 Wave 1 — 待 /blueprint 或 /forge 设置
+_尚未开始执行_
+
+---
+
+## 🌳 项目结构 (Project Tree)
+
+> **注意**: 此部分由 `/genesis` 维护。
+
+```text
+(等待 Genesis 初始化结构树...)
+```
+
+---
+
+## 🧭 导航指南 (Navigation Guide)
+
+> **注意**: 此部分由 `/genesis` 维护。
+
+- **在新架构就绪前**: 请勿大规模修改代码。
+- **遇到架构问题**: 请查阅 `genesis/v{N}/03_ADR/`。
+
+---
+
+## 🛠️ 工作流注册表
+
+| 工作流 | 触发时机 | 产出 |
+|--------|---------|------|
+| `/quickstart` | 新用户入口 / 不知道从哪开始 | 编排其他工作流 |
+| `/genesis` | 新项目 / 重大重构 | PRD, Architecture, ADRs |
+| `/scout` | 变更前 / 接手项目 | `genesis/v{N}/00_SCOUT_REPORT.md` |
+| `/design-system` | genesis 后 | 04_SYSTEM_DESIGN/*.md |
+| `/blueprint` | genesis 后 | 05_TASKS.md + agents.md 初始 Wave |
+| `/change` | 微调已有任务 | 更新 TASKS + SYSTEM_DESIGN (仅修改) + CHANGELOG |
+| `/explore` | 调研时 | 探索报告 |
+| `/challenge` | 决策前质疑 | 07_CHALLENGE_REPORT.md (含问题总览目录) |
+| `/forge` | 编码执行 | 代码 + 更新 agents.md Wave 块 |
+| `/craft` | 创建工作流/技能/提示词 | Workflow / Skill / Prompt 文档 |
+
+---
+
+## 📜 宪法 (The Constitution)
+
+1. **版本即法律**: 不"修补"架构文档，只"演进"。变更必须创建新版本。
+2. **显式上下文**: 决策写入 ADR，不留在"聊天记忆"里。
+3. **交叉验证**: 编码前对照 `05_TASKS.md`。我在做计划好的事吗？
+4. **美学**: 文档应该是美的。善用 Markdown 和 Emoji。
+
+---
+## 🔄 Auto-Updated Context
+
+<!-- AUTO:BEGIN — 由工作流自动维护，请勿手动编辑此区块 -->
+
+### 技术栈决策
+- [由 genesis/tech-evaluator 自动填充]
+
+### 系统边界
+- [由 genesis/system-architect 自动填充]
+
+### 活跃 ADR
+- [由 genesis 自动填充 ADR 摘要]
+
+### 当前任务状态
+- [由 blueprint/forge 自动更新]
+
+<!-- AUTO:END -->
+
+---
+> **状态自检**: 准备好了？提醒用户运行 `/quickstart` 开始吧。

package/templates/.agent/skills/design-reviewer/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: design-reviewer
+description: 使用三维框架（系统设计、运行模拟、工程实现）系统性审查架构和系统设计文档。产出按严重度分级的发现，关联到具体文档段落。
+---
+
+# 设计审查大师手册
+
+> "代码之前发现的设计缺陷，能省下一百个 Bug。  
+> 对设计严厉，代码才能优雅。"
+
+你是**设计审查大师**，负责系统性审查架构和系统设计文档。你的三维框架确保没有任何一类风险被遗漏。
+
+---
+
+## ⚡ 任务目标
+
+1. **加载文档 (必须)**: 读取 `02_ARCHITECTURE_OVERVIEW.md`、所有 `04_SYSTEM_DESIGN/*.md` 以及所有 `03_ADR/*.md`。
+2. **深度理解**: 使用 `sequentialthinking`（3-5 步）在批判之前先理解设计意图。
+3. **Pre-Mortem**: 想象项目在 6 个月后失败了——倒推根因。
+4. **三维审查**: 系统性执行全部 3 个维度。
+5. **假设验证**: 识别隐藏假设并尝试证伪。
+6. **生成发现**: 为每条发现标注严重度，并关联到具体文档段落。
+
+## 🛑 硬约束
+
+- **证据为本**: 每条发现**必须**有具体文档引用 + 推理链。"可能有性能问题"这种没有分析的说法禁止出现。
+- **质量优于数量**: 3 条真实发现 > 10 条猜测。
+- **尊重 ADR 决策**: 如果 ADR 明确选择了某个权衡并附有文档化的理由，不要翻旧账。仅在出现新证据反驳原有理由时才标记。
+- **不涉及实现细节**: 审查的是*设计*，不是假想的代码。
+
+---
+
+## 🔍 三维审查框架
+
+### 维度 1: 系统设计 (System Design)
+
+**目标**: 验证架构的完整性、一致性和边界清晰度。
+
+| # | 检查项 | 关注要点 |
+|---|--------|---------|
+| SD-1 | **架构一致性** | 同一组件在 PRD、Architecture、System Design 中的描述是否矛盾？ |
+| SD-2 | **边界清晰度** | 每个系统的职责范围是否明确？是否存在职责重叠？ |
+| SD-3 | **依赖合理性** | 系统依赖是否无环？是否存在隐藏耦合？ |
+| SD-4 | **接口完整性** | 所有跨系统接口是否完整定义（输入/输出/错误/协议）？ |
+| SD-5 | **状态管理** | 系统状态转换是否清晰定义？边缘状态是否处理？ |
+| SD-6 | **数据模型完整性** | 实体关系是否跨文档一致？是否存在孤儿实体？ |
+
+**思考提示**（配合 `sequentialthinking` 使用）:
+1. "这个架构背后的核心假设是什么？"
+2. "如果假设 X 不成立，什么会崩？"
+3. "系统边界定义是否存在歧义？"
+4. "接口是否覆盖了所有边界情况？"
+
+---
+
+### 维度 2: 运行模拟 (Runtime Simulation)
+
+**目标**: 在脑中"运行"系统，发现时序、状态和并发问题。
+
+> 本维度**必须**使用 `sequentialthinking`（3-5 步）。运行时问题藏在序列中。
+
+| # | 检查项 | 关注要点 |
+|---|--------|---------|
+| RS-1 | **时序一致性** | 时序模型是否合理？是否存在"必须先于"的矛盾？ |
+| RS-2 | **状态同步** | 分布式状态下，副本是否可能发散？最终一致性在这里是否可接受？ |
+| RS-3 | **并发处理** | 两个操作冲突时会怎样？是否有解决策略？ |
+| RS-4 | **边界条件** | 空状态、满状态、溢出——各自如何处理？ |
+| RS-5 | **故障传播** | 组件 A 故障时如何影响 B、C？是否存在级联风险？ |
+| RS-6 | **Happy Path 偏见** | 只设计了正常路径？错误/超时/部分失败路径呢？ |
+
+**思考提示**:
+1. "端到端追踪一个典型操作，经过哪些步骤？"
+2. "每一步产生什么状态变更？什么可能出错？"
+3. "如果两个用户同时做同一件事会怎样？"
+4. "崩溃后 30 秒，系统是什么样子？"
+
+---
+
+### 维度 3: 工程实现 (Engineering Implementation)
+
+**目标**: 验证设计可构建、可测试、可维护。
+
+> 本维度**必须**使用 `sequentialthinking`（3-5 步）。
+
+| # | 检查项 | 关注要点 |
+|---|--------|---------|
+| EI-1 | **可测试性** | 核心逻辑能否被单元测试？是否有 Mock 的接缝？ |
+| EI-2 | **可维护性** | 如果需求变更，需要改多少文件？ |
+| EI-3 | **性能瓶颈** | 设计中是否隐藏了 N+1 查询、无界循环或 O(n²)？ |
+| EI-4 | **安全面** | 认证边界是否清晰？敏感数据静态/传输加密？输入校验？ |
+| EI-5 | **可观测性** | 凭设计中的日志/指标方案能否调试生产问题？ |
+| EI-6 | **技术栈契合度** | 选定的技术是否真正支持所需功能？版本兼容性？ |
+
+**思考提示**:
+1. "如何为核心逻辑写单元测试？"
+2. "如果需要修改功能 X，影响范围多大？"
+3. "性能热点在哪？能否后续优化？"
+4. "这个设计暴露了哪些攻击向量？"
+
+---
+
+## 🎚️ 严重度分级
+
+| 等级 | 判定标准 | 所需行动 |
+|:----:|---------|---------|
+| **Critical** 🔴 | 根本性矛盾或不可能实现。不解决无法继续。 | P0 — 必须在 blueprint/forge 之前修复 |
+| **High** 🟠 | 大概率导致返工或失败的严重风险。 | P1 — 在 forge 之前修复 |
+| **Medium** 🟡 | 有变通方案的质量隐患。 | P2 — 实现阶段修复 |
+| **Low** 🟢 | 润色项或轻微不一致。 | P3 — 后续跟踪 |
+
+---
+
+## 📊 输出格式
+
+按以下结构生成发现，适合纳入 `07_CHALLENGE_REPORT.md`：
+
+```markdown
+## 🔍 设计审查发现
+
+### 摘要
+
+| 维度 | 发现数 | Critical | High | Medium | Low |
+|------|:------:|:--------:|:----:|:------:|:---:|
+| 系统设计 | — | — | — | — | — |
+| 运行模拟 | — | — | — | — | — |
+| 工程实现 | — | — | — | — | — |
+| **合计** | **—** | **—** | **—** | **—** | **—** |
+
+---
+
+### [维度] — [ID]: [标题]
+
+**严重度**: Critical / High / Medium / Low
+**文档位置**: [精确的文件和章节引用]
+
+**问题**:
+[详细描述，引用具体文档内容]
+
+**证据**:
+- 文档分析: [来自 PRD/Architecture/ADR 的具体内容]
+- 推理链: [基于 sequentialthinking 的分析]
+- 类比: [其他系统中的类似已知失败，如适用]
+
+**影响**:
+- [不修复会发生什么]
+
+**建议**:
+[修复方式，可提供多个选项]
+```
+
+---
+
+## 💡 审查质量清单
+
+交付发现前，确认：
+- [ ] 每条发现有具体文档引用（不是笼统的"架构文档"）
+- [ ] 每条发现有明确的影响说明
+- [ ] 没有纯猜测性的发现（缺乏推理链条）
+- [ ] Critical/High 发现经过 `sequentialthinking` 验证
+- [ ] ADR 中已记录的权衡被尊重（没有在无新证据的情况下重复质疑）
+- [ ] 发现可操作（审查者能根据建议进行修复）

package/templates/.agent/skills/spec-writer/SKILL.md

@@ -18,6 +18,8 @@ Your job is to kill ambiguity.
     *   Draft clarifying questions
 3.  **Interrogate**: Present questions to user. DO NOT proceed without answers.
 4.  **Draft PRD (MANDATORY)**: Use `view_file references/prd_template.md` then `write_to_file` to create `genesis/v{N}/01_PRD.md`.
+5.  **Ambiguity Scan (MANDATORY)**: After drafting, run the 10-Dimension Ambiguity Scan (see below). Fix issues inline or mark `[ASSUMPTION]`.
+6.  **US Quality Gate (MANDATORY)**: Verify every User Story passes the quality checklist (see below).
 
 ## 🛑 Mandatory Steps
 Before creating the PRD, you MUST:
@@ -26,6 +28,11 @@ Before creating the PRD, you MUST:
 3. Clarify "Vibe Words" with the user (What does "Fast" mean to you? What does "Modern" imply?).
 4. Use `write_to_file` to save output. DO NOT just print to chat.
 
+After creating the PRD, you MUST:
+5. Run the 10-Dimension Ambiguity Scan — fix or mark all `Partial`/`Missing` items.
+6. Verify every User Story has: Priority / 独立可测 / 涉及系统 / 边界情况.
+7. Ensure `[NEEDS CLARIFICATION]` tags ≤ 3 (hard limit). Excess → use reasonable defaults + `[ASSUMPTION]` tag.
+
 ## ✅ Completion Checklist
 - [ ] PRD file created: `genesis/v{N}/01_PRD.md`
 - [ ] Contains User Stories, Acceptance Criteria, Non-Goals
@@ -56,3 +63,46 @@ Before creating the PRD, you MUST:
 
 ## 🧰 The Toolkit
 *   `references/prd_template.md`: The Product Requirements Document template.
+
+## 🔍 10-Dimension Ambiguity Scan
+
+After drafting the PRD, you **MUST** systematically scan it against these 10 dimensions. This replaces ad-hoc "any questions?" with a **repeatable, exhaustive** sweep.
+
+For each dimension, mark status: `Clear` ✅ / `Partial` ⚠️ / `Missing` ❌
+
+| # | Dimension | What to Check | Status |
+|---|-----------|--------------|:------:|
+| 1 | **Functional Scope & Behavior** | Core objectives / success criteria / explicit exclusions / user role distinctions | |
+| 2 | **Domain & Data Model** | Entities, attributes, relationships / uniqueness rules / lifecycle & state transitions / data volume assumptions | |
+| 3 | **Interaction & UX Flow** | Key user journeys / error, empty, loading states / accessibility & i18n | |
+| 4 | **Non-Functional Quality** | Performance / scalability / reliability / observability / security & privacy / compliance | |
+| 5 | **Integration & External** | External service failure modes / import-export formats / protocol version assumptions | |
+| 6 | **Edge Cases & Failure** | Negative scenarios / rate limiting / concurrency conflict resolution | |
+| 7 | **Constraints & Tradeoffs** | Technical constraints / explicit tradeoff records / rejected alternative archives | |
+| 8 | **Terminology Consistency** | Canonical glossary / synonym normalization across PRD | |
+| 9 | **Completion Signals** | Acceptance criteria testability / quantifiable DoD | |
+| 10 | **Placeholders** | TODO markers / unquantified vague adjectives (fast, scalable, secure, intuitive, robust) | |
+
+**Rules**:
+- `Partial` or `Missing` items → rank by **Impact × Uncertainty**, pick **top 5** to ask user
+- Ask **one question at a time**; provide your recommended answer; user can accept or customize
+- After user answers → **atomically write** the answer into the corresponding PRD section (never leave contradictory text)
+- **NEEDS CLARIFICATION hard limit ≤ 3** — if more remain, fill with reasonable defaults + `[ASSUMPTION: ...]` tag
+- **Do NOT ask about these reasonable defaults**: industry-standard data retention, standard web/mobile performance expectations, user-friendly error messages with fallbacks, standard session-based or OAuth2 auth
+
+## ✅ User Story Quality Gate
+
+Every User Story in the PRD **MUST** pass these checks before the PRD is considered complete:
+
+| Check | Requirement |
+|-------|------------|
+| **Unique ID** | Has `[REQ-XXX]` identifier for traceability |
+| **Priority** | Marked P0 / P1 / P2 — P0 stories listed first |
+| **独立可测** | Describes how this story can be **independently** demonstrated and verified |
+| **涉及系统** | Lists specific system IDs (must align with `02_ARCHITECTURE_OVERVIEW.md`) |
+| **Acceptance Criteria** | At least 1 Given-When-Then + at least 1 Error Case |
+| **边界情况** | At least 1 boundary condition identified |
+| **No Vibe Words** | No unquantified adjectives (fast → <100ms p99, scalable → support N users) |
+| **User Value** | One sentence describing value to end user |
+
+If any User Story fails a check → fix it before delivering the PRD.