@zeyue0329/xiaoma-cli 1.11.0 → 1.13.0

package/src/core/tasks/xiaoma-create-prd/data/prd-purpose.md

@@ -195,3 +195,160 @@ Certain industries have mandatory requirements that must be present:
 ---
 
 **Remember:** The PRD is the foundation. Quality here ripples through every subsequent phase. A dense, precise, well-traced PRD makes UX design, architecture, epic breakdown, and AI development dramatically more effective.
+
+---
+
+## Chinese PRD Anti-Patterns (中文 PRD 反模式)
+
+When `{document_output_language}` is Chinese, the same density/SMART/no-leakage rules apply, but a few culture-specific traps appear repeatedly. Each anti-pattern is numbered (AP-NN) so the validation rubric (`xiaoma-validate-prd/data/prd-quality-rubric.csv`) can reference it directly via `detection_signals`.
+
+### AP-01 — 口号化目标 (Slogan-style goals)
+
+PRDs written in Chinese B2B contexts often inherit marketing copy from internal slide decks. The result is unmeasurable, multi-claim sentences.
+
+- **Detection signals:** "打造", "业界领先", "一站式", "赋能", "数字化转型", "智能化", "全方位"
+- ❌ Bad: "打造业界领先的、智能化、一站式客户成功平台，赋能企业数字化转型。"
+- ✅ Good: "Vision — 让中型企业的客户成功团队在统一画布上看见、解读并干预客户旅程，把流失预警的发现到触达从平均 7 天压到 24 小时内。"
+- **Self-check:** 这一句能映射到至少 1 条可量化的 Success Criteria 吗？如果不能，重写。
+
+### AP-02 — 模糊主语 (Ambiguous subject)
+
+Chinese drops subjects more readily than English, which makes "系统应支持..." sentences feel natural but breaks FR traceability.
+
+- **Detection signals:** "系统应支持", "应当能够", "可以实现", subject-less imperative
+- ❌ Bad: "系统应支持客户档案的查询和管理。"
+- ✅ Good: "FR-PROFILE-01: CSM 可以按公司名 / 标签 / 客户健康度区间检索客户档案。"
+- **Self-check:** Every FR sentence starts with `[Actor]` (CSM, Admin, system, ...)? If actor is "system", is it because no human user is involved (e.g., scheduled jobs)?
+
+### AP-03 — 实现泄漏 (Implementation leakage)
+
+Tech stack names sneak in when authors come from engineering. PRD must describe *what*, not *how*.
+
+- **Detection signals:** "Redis", "PostgreSQL", "Kafka", "JWT", "WebSocket", "Spring Boot", "Vue", any technology proper noun
+- ❌ Bad: "FR-X: 系统使用 Redis 缓存订单查询结果，TTL 30 分钟。"
+- ✅ Good: "FR-ORDER-04: 订单查询 p95 < 200ms（移到 §9 NFR）。"
+- **Self-check:** Does this FR say *what capability exists* or *how it's built*? If "how", strip the tech and either restate as capability or move to NFR.
+
+### AP-04 — 复合需求 (Compound requirements)
+
+A single FR that bundles 2-3 distinct capabilities. Decomposes into multiple stories, breaks 1 FR ↔ 1-3 story mapping.
+
+- **Detection signals:** "且", "并", "同时", "以及", "并且能够"
+- ❌ Bad: "FR-Y: CSM 可以查询客户、添加标签并导出 Excel。"
+- ✅ Good: 拆为 FR-PROFILE-01（查询）/ FR-PROFILE-03（标签）/ FR-EXPORT-02（导出）
+- **Self-check:** Count the verbs in the FR. > 1 verb usually means split. Use the "Channel / Data Object / Action" axis from FR-to-Story Heuristics below.
+
+### AP-05 — 量词缺失 (Missing quantifiers)
+
+Subjective adjectives appear in success criteria and NFRs.
+
+- **Detection signals:** "显著", "明显", "极大", "尽可能", "高效", "快速", "稳定", "良好"
+- ❌ Bad: "客户满意度显著提升，流失率明显下降。"
+- ✅ Good: "SC-02 客户满意度 NPS ≥ 45（季度调研，N ≥ 100）；SC-03 月度流失率从 4.2% 降至 ≤ 2.5%（CRM 仪表板）。"
+- **Self-check:** Does every success metric carry baseline + target + measurement + time window?
+
+---
+
+## FR-to-Story Heuristics (FR→Story 启发式映射规则)
+
+A FR is the capability contract; user stories are the implementation contract. The PM agent uses these heuristics during `step-09-functional` to keep FR granularity right-sized for downstream Epic/Story breakdown.
+
+### Rule 1 — 1 FR maps to 1-3 stories
+
+A FR that decomposes into 4+ stories is too coarse — split it. A FR that decomposes into 0 stories is either redundant with another FR or belongs to NFR.
+
+- 1 story: simple CRUD or read-only capability
+- 2 stories: capability + admin/config variant
+- 3 stories: capability + read-side + write-side (or empty / typical / extreme states)
+
+### Rule 2 — Single Actor only
+
+If a FR mentions two actors, split. Two actors = two journeys = two FRs.
+
+- ❌ "Admin and CSM can both export reports." → split into FR-REPORT-01 (Admin) + FR-REPORT-02 (CSM)
+- Exception: when the actor is "system" for a background job, this rule doesn't apply.
+
+### Rule 3 — "且 / 并 / 同时" usually signals a split
+
+Composite requirements (AP-04 above) are the most common over-coarse pattern. The connective itself is a refactor signal.
+
+### Rule 4 — Split axes
+
+When unclear how to split, use these axes in priority order:
+
+1. **Actor** — who performs it (CSM vs. Admin vs. system)
+2. **Action verb** — what they do (create vs. read vs. update vs. delete)
+3. **Data object** — what they act on (customer vs. tag vs. ticket)
+4. **Channel** — through what surface (web vs. API vs. webhook)
+
+### Rule 5 — Capability area naming
+
+Capability areas (the §8 sub-headers grouping FRs) must be **noun phrases**.
+
+- ✅ "客户档案管理" / "Customer Profile Management"
+- ❌ "管理客户档案" / "Manage Customer Profiles" (verb phrase = becomes a story title, not a capability area)
+
+Suggested area prefixes when generating FR IDs: `PROFILE`, `JOURNEY`, `RISK`, `SUMMARY`, `TICKET`, `TENANT`, `AUTH`, `EXPORT`, `INTEGRATE`, `AUDIT`.
+
+---
+
+## NFR Industry Baselines (NFR 行业基准库)
+
+When the PM agent reaches `step-10-nonfunctional`, it selects a profile based on `project-types.csv` detection in `step-07`, then uses these baselines as the default candidate list. The user can override any threshold during the A/P/C menu, but every NFR must end up with a quantitative threshold + measurement method.
+
+### Profile selection rules
+
+1. If `project_type ∈ {saas_b2b, web_app}` and target users are external paying customers → **SaaS B2B**
+2. If `project_type ∈ {developer_tool, cli_tool}` or target is internal-only → **Internal Tool**
+3. If consumer-facing, public traffic, or expected ≥ 10k concurrent users → **High-concurrency C-end**
+4. Unmatched → fall back to **SaaS B2B** (most stringent middle ground)
+
+### Baseline matrix
+
+| Dimension       | SaaS B2B (默认)                                                   | Internal Tool                  | High-concurrency C-end                       |
+| --------------- | ----------------------------------------------------------------- | ------------------------------ | -------------------------------------------- |
+| Performance     | API p95 < 500ms · p99 < 1.5s · 页面 LCP < 2.5s                    | API p95 < 1s · LCP < 4s        | API p95 < 200ms · p99 < 800ms · LCP < 1.8s   |
+| Availability    | 月度 SLA 99.9% · RTO < 4h · RPO < 15min                           | SLA 99.5% · RTO < 1 day        | SLA 99.95% · RTO < 30min · RPO < 1min        |
+| Security        | OWASP Top 10 全覆盖 · TLS 1.2+ · 静态加密 AES-256 · MFA 可选       | RBAC 强制 · TLS 1.2+           | + DDoS 防护 · WAF · 风控规则引擎             |
+| Scalability     | 单租户 1k 并发 · 横向扩容 ≤ 5min                                  | 100 并发 (内部工具)            | 50k QPS · 弹性扩容触发延迟 < 2min            |
+| Observability   | 关键链路 trace 覆盖 ≥ 95% · 错误率告警 < 5min · 日志保留 90d       | 日志保留 30d · 错误日志告警    | + RUM 全采样 · 业务指标分钟级 · 日志保留 1y  |
+| Compliance      | 数据本地化 · 等保二级 · 审计日志 ≥ 180d · 个保法授权链             | 等保二级 (推荐)                | + 个保法专项 · 跨境数据评估 · 行业专项合规    |
+
+### Per-NFR template
+
+```
+NFR-<DIM>-<NN>: [metric] [condition] [threshold] (measured by [method]) [profile=<profile-name>]
+```
+
+Example (SaaS B2B):
+
+> NFR-PERF-01: API 接口在正常负载下 p95 < 500ms（APM 监控统计，profile=saas_b2b）
+
+When the threshold deviates from the baseline (either tighter or looser), the NFR must include a one-line **rationale**. Example:
+
+> NFR-AVAIL-01: 月度 SLA ≥ 99.95%（profile=saas_b2b override；rationale: 试点客户 SLA 合同要求 99.95%）
+
+---
+
+## Dual-Audience Writing Checklist
+
+A PRD that scores well on this checklist works equally well for the human reviewer (skim → skip → scan) and the LLM downstream consumer (chunk → anchor → cite).
+
+### Human-readable path (Skim · Skip · Scan)
+
+1. **Skim** — Reading only `## Level 2` headers reveals the full structure of the document
+2. **Skip** — Each section opens with a 1-2 sentence summary; reader can skip the rest if not relevant
+3. **Scan** — Tables, bulleted lists, and bolded keywords carry the dense data; prose is minimal
+
+### LLM-consumable path (Chunk · Anchor · Cite)
+
+4. **Chunk** — One concept per paragraph; paragraphs are separable without context loss
+5. **Anchor** — Every section/sub-section has a stable header used for cross-reference (`§N`, `FR-AREA-NN`)
+6. **Cite** — Cross-references inside the PRD use full IDs (e.g., `FR-PROFILE-01` not "the customer search FR")
+
+### Self-contained sections
+
+7. **Forward reference free** — A section never depends on reading a later section to be understood
+8. **Section-local definitions** — Domain terms first introduced in a section are defined within or linked to §5 Domain Requirements terminology table
+
+A section that fails 2+ checklist items is a D13 Dual-Audience Readiness flag in the validation rubric.

package/src/core/tasks/xiaoma-create-prd/data/upstream-input-contract.md

@@ -0,0 +1,168 @@
+# Analyst → PM Upstream Input Contract
+
+> **Purpose:** Specify what the PM agent (xiaochan / 小蝉) requires from upstream Analyst (xiaofen / 小芬) artifacts when starting `xiaoma-create-prd`. Defines required fields, where they map into the PRD's 9 sections, and how to handle missing fields.
+>
+> **Loaded by:** `steps-c/step-01-init.md` (PRD initialization) and `auto-requirements-pipeline/steps/step-04-create-prd.md` (pipeline delegation).
+>
+> **Authoritative for:** Validation dimension D04 (Brief Coverage) in `xiaoma-validate-prd`.
+
+---
+
+## 1. Scope and Applicability
+
+This contract applies whenever PRD creation is started **from upstream artifacts** rather than from scratch (i.e., `inputDocuments` array is non-empty after step-01 discovery).
+
+It applies in two execution modes:
+
+| Mode                | Triggered by                       | Behavior on missing fields                                              |
+| ------------------- | ---------------------------------- | ----------------------------------------------------------------------- |
+| **Interactive**     | User invokes `pm *create-prd`      | `reverse-ask` policy — pause and request from user / Analyst            |
+| **Pipeline (auto)** | `auto-requirements-pipeline` step 4 | Degrade `reverse-ask` to `placeholder` + write to `pipeline-status.json.blockers[]` |
+
+Pipeline mode never blocks indefinitely on missing input — placeholders are tracked and surfaced by `step-08-finalize` as human-fixup tasks.
+
+---
+
+## 2. Upstream Artifact Catalog
+
+Four artifact types feed PRD creation. Each is produced by a specific Analyst skill / workflow:
+
+| Artifact              | Producer skill                  | Default file pattern                                          | Authoritative section reference              |
+| --------------------- | ------------------------------- | ------------------------------------------------------------- | -------------------------------------------- |
+| **Product Brief**     | `skill:xiaoma-create-product-brief` | `{planning_artifacts}/product-brief.md` or `*brief*.md`     | step files: vision · users · metrics · scope |
+| **Market Research**   | `skill:xiaoma-market-research`  | `{planning_artifacts}/research/market-*.md`                   | step files: customer-behavior · pain-points · decisions · competitive-analysis |
+| **Domain Research**   | `skill:xiaoma-domain-research`  | `{planning_artifacts}/research/domain-*.md`                   | step files: domain-analysis · regulatory-focus · technical-trends |
+| **Technical Research**| `skill:xiaoma-technical-research` | `{planning_artifacts}/research/technical-*.md`              | step files: technical-overview · integration-patterns · architectural-patterns · implementation-research |
+
+PM agent **must** load all four if present. Absence of a research file is acceptable — they are optional inputs. Absence of `product-brief.md` triggers `reverse-ask` (see §4).
+
+---
+
+## 3. Required Fields per Artifact
+
+Each table lists the fields the PM agent extracts. `Source heading` is the H2/H3 the field was written under by the upstream workflow.
+
+### 3.1 Product Brief (`product-brief.md`)
+
+| Field                    | Required | Source heading              | Maps to PRD §        | Missing-field strategy |
+| ------------------------ | -------- | --------------------------- | -------------------- | ---------------------- |
+| `vision_statement`       | yes      | `## Vision`                 | §1 Executive Summary | reverse-ask            |
+| `core_problem`           | yes      | `## Vision` (problem para)  | §1 Executive Summary | reverse-ask            |
+| `target_personas`        | yes      | `## Target Users`           | §1 + §4 Journeys     | reverse-ask            |
+| `value_propositions`     | yes      | `## Vision` (value para)    | §1 Executive Summary | reverse-ask            |
+| `success_metrics_draft`  | yes      | `## Success Metrics`        | §2 Success Criteria  | reverse-ask            |
+| `mvp_scope`              | yes      | `## Scope` (in-scope)       | §3 Product Scope     | reverse-ask            |
+| `out_of_scope`           | partial  | `## Scope` (out-of-scope)   | §3 Product Scope     | placeholder            |
+| `constraints`            | optional | `## Scope` (constraints)    | §3 Product Scope     | skip                   |
+| `differentiation`        | partial  | `## Vision` (diff para)     | §1 + §6 Innovation   | placeholder            |
+
+### 3.2 Market Research (`market-*.md`)
+
+| Field                    | Required | Source heading                | Maps to PRD §           | Missing-field strategy |
+| ------------------------ | -------- | ----------------------------- | ----------------------- | ---------------------- |
+| `customer_behavior`      | partial  | `## Customer Behavior`        | §4 Journeys (context)   | placeholder            |
+| `pain_points`            | partial  | `## Pain Points`              | §1 + §4 + §8 (driver of FRs) | placeholder       |
+| `decision_factors`       | partial  | `## Customer Decisions`       | §1 differentiation · §6 | placeholder            |
+| `competitive_analysis`   | partial  | `## Competitive Analysis`     | §6 Innovation Analysis  | placeholder            |
+
+If `competitive_analysis` is missing AND `domain_complexity` (from `domain-complexity.csv`) is `medium` or `high`, escalate to **reverse-ask** instead of placeholder — competitive context is load-bearing for the Innovation section in those domains.
+
+### 3.3 Domain Research (`domain-*.md`)
+
+| Field                    | Required | Source heading                | Maps to PRD §            | Missing-field strategy |
+| ------------------------ | -------- | ----------------------------- | ------------------------ | ---------------------- |
+| `regulatory_landscape`   | conditional | `## Regulatory Focus`      | §5 Domain Requirements   | `reverse-ask` if domain ∈ high-complexity (healthcare/fintech/govtech/aerospace/etc.); else skip |
+| `domain_terminology`     | partial  | `## Domain Analysis`          | §5 (terminology table)   | placeholder            |
+| `technical_trends`       | partial  | `## Technical Trends`         | §6 + §7                  | skip                   |
+| `competitive_landscape`  | partial  | `## Competitive Landscape`    | §6                       | skip (overlaps with market research) |
+
+### 3.4 Technical Research (`technical-*.md`)
+
+| Field                    | Required | Source heading                | Maps to PRD §             | Missing-field strategy |
+| ------------------------ | -------- | ----------------------------- | ------------------------- | ---------------------- |
+| `technical_overview`     | partial  | `## Technical Overview`       | §7 Project-Type Reqs      | skip                   |
+| `integration_patterns`   | partial  | `## Integration Patterns`     | §7 + §9 NFR (integration latency) | skip            |
+| `architectural_constraints` | partial | `## Architectural Patterns`  | §7 + §9 NFR scalability   | skip                   |
+| `implementation_options` | optional | `## Implementation Research`  | informational only — **DO NOT** copy into PRD (implementation leakage AP-03) | skip |
+
+**Important:** Technical research is the highest-risk source for AP-03 (implementation leakage). PM agent must extract NFR-shaping facts (latency, scale, integration) but **strip technology names, library choices, and concrete architecture decisions** before writing into the PRD.
+
+---
+
+## 4. Missing-Field Strategy
+
+Three policies, escalated by severity:
+
+### 4.1 `reverse-ask` (interactive only)
+
+- PRD workflow pauses at `step-01-init` (or wherever the missing field would be consumed)
+- PM agent writes a clear request: "Need `<field>` from `<artifact>`. Source heading expected: `<heading>`. Continue from upstream Analyst (`/analyst *<command>`) or paste here."
+- Output PRD frontmatter is not yet written; no placeholders are introduced
+- **Pipeline override:** in `auto-requirements-pipeline`, this policy degrades to `placeholder` + a `blockers[]` entry, so the pipeline does not deadlock
+
+### 4.2 `placeholder`
+
+- Insert literal `{{TBD: <field> from <artifact>}}` at the mapped PRD location
+- Add an entry to PRD frontmatter: `tbds: [{field, artifact, suggested_command}]`
+- `step-11-polish` is responsible for surfacing all unresolved `{{TBD: ...}}` markers and refusing to mark the PRD complete until they are resolved or explicitly waived
+- In pipeline mode, `step-08-finalize` aggregates remaining TBDs into a human-fixup task list
+
+### 4.3 `skip`
+
+- Field is treated as not required for this PRD
+- PRD frontmatter `inputDocuments` entry adds `partial: [<field>]` so validation D04 (Brief Coverage) can still report it as a known gap, not silent omission
+
+---
+
+## 5. PRD-Section Reverse Index
+
+A view of the same mapping organized by PRD section. Used by PM agent during `step-02c` through `step-10` — when authoring a section, read the corresponding row to know which upstream fields to consult.
+
+| PRD §                          | Pulls from (artifact.field)                                                                                                                                  | Merge rule                                                                                       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| §1 Executive Summary           | `brief.vision_statement`, `brief.core_problem`, `brief.target_personas`, `brief.value_propositions`, `brief.differentiation`, `market.pain_points` (context) | brief is authoritative; market provides supporting evidence; densify, don't concatenate          |
+| §2 Success Criteria            | `brief.success_metrics_draft`                                                                                                                                | brief metrics are starting drafts; PM must add baseline + measurement + window if missing        |
+| §3 Product Scope               | `brief.mvp_scope`, `brief.out_of_scope`, `brief.constraints`                                                                                                  | brief is authoritative; PM may refine but not silently drop items                                |
+| §4 User Journeys               | `brief.target_personas`, `market.customer_behavior`, `market.pain_points`                                                                                     | brief defines personas; market provides journey context — synthesize, do not copy verbatim       |
+| §5 Domain Requirements         | `domain.regulatory_landscape`, `domain.domain_terminology` + `domain-complexity.csv`                                                                          | CSV defines required `special_sections`; domain research fills them; mark "N/A" if `general` low |
+| §6 Innovation Analysis         | `brief.differentiation`, `market.competitive_analysis`, `market.decision_factors`                                                                             | combine for differentiation narrative; mark "N/A" only if no external competition                |
+| §7 Project-Type Requirements   | `project-types.csv` + `technical.technical_overview`, `technical.integration_patterns`, `technical.architectural_constraints`                                  | CSV defines `required_sections`; technical research informs but tech names are stripped (AP-03)  |
+| §8 Functional Requirements     | derived from §1, §3, §4, §5, §7 — **not** from upstream artifacts directly                                                                                    | FRs synthesized in step-09; upstream feeds §1-§7, FRs trace back to those                         |
+| §9 Non-Functional Requirements | `technical.architectural_constraints` (scale/latency facts), `domain.regulatory_landscape` (compliance NFRs) + `prd-purpose.md` NFR Industry Baselines       | profile selected per §7 project type; baselines are defaults, upstream facts override            |
+
+---
+
+## 6. Pipeline Integration Points
+
+For `auto-requirements-pipeline/workflow.md`:
+
+1. **Step 1 init** — verify `req.md` exists (pipeline trigger doc) and at least one of `product-brief.md` exists. If neither, abort pipeline with a clear error.
+
+2. **Step 4 create-prd (delegation)** — before invoking `xiaoma-create-prd`:
+   - Run `validate_upstream_contract(inputDocuments)`:
+     - Iterate §3 tables; for each `required: yes` field, check existence in source heading
+     - Iterate `conditional` fields; check trigger condition then existence
+     - Output `{planning_artifacts}/contract-check.json`:
+       ```
+       {
+         "passed": false,
+         "missing_required": [{"artifact": "...", "field": "...", "expected_heading": "..."}],
+         "missing_conditional": [...],
+         "applied_policies": {"<field>": "placeholder|reverse-ask|skip"}
+       }
+       ```
+   - In pipeline mode, downgrade all `reverse-ask` to `placeholder` and append entries to `pipeline-status.json.blockers[]`. Continue.
+   - In interactive mode, if any required field missing, halt PRD creation and surface the request.
+
+3. **Step 5 validate-prd** — `step-v-04-brief-coverage-validation` reads `contract-check.json` as evidence:
+   - Pass if `missing_required.length == 0` and `tbds` resolved
+   - Partial if `missing_required.length == 0` and `tbds.length > 0` but ≤ 3
+   - Fail if `missing_required.length > 0` OR `tbds.length > 3`
+
+---
+
+## 7. Versioning and Updates
+
+- This contract is versioned with `prd-purpose.md` (same milestone bumps).
+- When upstream Analyst workflows change their step files (renaming a heading, adding/removing a step), the §3 tables here must be updated in the same PR. The validation refs `xiaoma-validate-prd/data/prd-quality-rubric.csv` D04 row references field names from §3 — keep in sync.
+- Reference paths (file locations, step file names) tracked here are validated by `npm run validate:refs`.