@ngocsangairvds/vsaf 4.1.25 → 4.1.26

package/skills/sdlc/ba-validate-srs/steps-v/step-v-04-consistency.md

@@ -0,0 +1,352 @@
+---
+# model: sonnet
+# findingsOutput: '{output_folder}/_validation_temp/findings-consistency.yaml'
+# contextFile: '{output_folder}/_validation_temp/context.yaml'
+# grepPatterns: '../data/grep-patterns-srs.yaml'
+---
+
+# Step V-04: Consistency — Kiểm tra tính nhất quán
+
+---
+
+## 1. Intra-file consistency (trong cùng 1 file)
+
+Với mỗi SRS file, kiểm tra:
+
+### 1.1 ID patterns
+
+**Load context:** Read `{contextFile}` and `{grepPatterns}` → `id_patterns` group.
+
+Run Grep using `id_patterns` patterns against `srs_path`:
+- `uc_id_valid` pattern → find all UC IDs, check format UC-[A-Z]{2,4}-\d{2}
+- `screen_id_valid` pattern → find all SCR IDs, check format SCR-[A-Z]{2,4}-\d{2}  
+- `br_id_valid` pattern → find all BR IDs
+- `id_lowercase_violation` pattern → any lowercase ID violations?
+
+Cross-check BR IDs: every BR referenced in flow tables must appear in Section 5 summary (C-4 check):
+1. Grep `BR-[A-Z]{2,4}-\d{2,3}-\d{2,3}|BR-[A-Z]{2,4}-\d{3}` in flow sections → extract all referenced BR IDs
+2. Grep same pattern in Section 5 → extract all defined BR IDs
+3. Referenced but not defined → MEDIUM finding
+4. Defined but not referenced anywhere → LOW finding
+
+Item IDs: `uc_id_pattern`, `screen_id_pattern`, `error_code_consistency`, `br_code_consistency`
+
+### 1.2 Naming
+
+> **Template note (2026-04):** ERD section đã bị xóa — không còn ERD để đối chiếu entity naming. Check entity naming INTRA-FILE: đối chiếu cột "Bảng/Thực thể liên quan" trong các flow tables với nhau và với Section 5 BRs.
+
+- Actor names nhất quán giữa UC table và flow table (cột Đối tượng)? Đối chiếu với Section 1 row "Đối tượng sử dụng" (actor_naming)
+- Entity names nhất quán GIỮA CÁC UC flow tables (cột "Bảng/Thực thể liên quan")? (entity_naming) — không cần ERD nữa
+- State names nhất quán giữa State Diagram Section 8 và bảng mô tả? (state_naming)
+- Screen control names dùng đúng prefix convention: `txt`, `btn`, `lbl`, `chk`, `lnk`, `ddl`, `dt`, `img`? (screen_control_naming)
+- Steps trong Activity Diagram có đánh số `:(1)`, `:(2)` nhất quán không? (activity_diagram_step_numbering)
+
+### 1.3 References
+
+> **Template note (2026-04):** Error code format mới: `REC-NNN`, `PAY-NNN` hoặc HTTP status (401, 403...) — không còn dùng `ERR-XX-NNN`. Check format nhất quán TRONG file.
+
+- Error codes trong Section 3 khớp với bước trong flow (cột "Bước" trong bảng mã lỗi trỏ đến step trong activity diagram)? (error_code_consistency)
+- Error code format nhất quán trong cùng file? (VD: không trộn lẫn `REC-NNN` với `ERR-XX-NNN`) (error_code_consistency)
+- BR codes trong Section 5 khớp với nội dung UC? (br_code_consistency)
+- FR IDs trong Mini-RTM Section 9 khớp? (rtm_fr_match)
+
+---
+
+## 2. Cross-file consistency (so sánh giữa các files)
+
+**Cross-file consistency checks LUÔN LUÔN thực hiện** — KG cung cấp references tự động, không cần batch/full scope.
+
+### 2.1 Entity naming across files
+- Cùng entity (VD: Policy) có cùng field names không? (data_model_fields)
+  - Ví dụ: `policyId` vs `policy_id`, `userId` vs `customer_id`
+- Naming convention nhất quán? camelCase vs snake_case? (entity_naming)
+
+### 2.2 Entity naming across files (updated)
+
+> **Template note (2026-04):** ERD và DB schema không còn trong SRS → không thể check field-level data model. Thay bằng entity name consistency ACROSS FILES: cùng entity phải dùng cùng tên table/collection.
+
+- Cùng entity (VD: Policy, CustomerProfile) có cùng tên trong flow tables (cột "Bảng/Thực thể liên quan") giữa các SRS files không? (entity_naming)
+  - VD: FR4 dùng "CustomerProfile", FR2 dùng "customer_profile" → naming inconsistency
+- ~~canonical_model_match~~ — REMOVED (no ERD/data model in SRS)
+- ~~pk_fk_type_consistent~~ — REMOVED (no field-level schema in SRS)
+- ~~currency_type_convention~~ — REMOVED (no field-level schema in SRS)
+
+### 2.3 API patterns
+
+> **Template note (2026-04):** API endpoint specs không còn trong SRS. Check API path nhất quán chỉ khi API paths xuất hiện trong flow tables (cột Ghi chú hoặc ES: External System calls).
+
+- API paths trong flow tables (nếu có) dùng prefix nhất quán `/api/v1/`? (api_naming_pattern)
+- ~~api_contract_param_match~~ — REMOVED (API contracts in TSD, not SRS)
+
+### 2.4 State machine alignment (cross_file_state_machine_match)
+
+**Structured extraction approach (C-5) — more reliable than pure semantic comparison.**
+
+#### Step 1: Extract state lists via Grep (Haiku-tier work)
+
+From `{grepPatterns}` → `state_machine` pattern group:
+1. Run `plantuml_state` pattern against SRS file → extract all state names from state diagrams
+2. Run `state_transition` pattern → extract transition triggers
+3. Build `srs_states` list from extracted names
+
+From System SRS (use line range from `context.yaml` `kg.arch_key_sections` or targeted read of state section):
+4. Extract `system_states` list the same way
+
+#### Step 2: Compare YAML lists (Sonnet judgment)
+
+Compare `srs_states` vs `system_states`:
+- States in SRS but not in System SRS → document in finding (may be legitimate decomposition)
+- States in System SRS but not in feature SRS → check if applicable to this FR
+- Transition triggers inconsistent → HIGH finding
+- State count discrepancy > 2× → CRITICAL
+
+This replaces full semantic comparison with structured list comparison.
+
+Item IDs: `state_naming`, `cross_file_state_machine_match`
+
+### 2.5 Service ownership alignment (service_ownership_consistent)
+- Với mỗi entity/resource quan trọng (voucher, promotion, claim, policy):
+  - Tìm tất cả files đề cập entity này và xem service nào được giao ownership
+  - **CRITICAL** nếu: File A giao voucher validate/reserve cho pricing-service, nhưng File B+C giao cho promotion-service
+  - Đây là lỗi boundary thực sự, không phải naming — có thể dẫn đến implement sai service
+- Cách check: search tên entity + action (validate, reserve, apply) → xem subject service
+
+### 2.8 State name uc-vs-diagram alignment (state_name_uc_vs_diagram)
+- So sánh tên states được dùng trong UC flow steps với tên states trong State Diagram (section 9):
+  - Mỗi status/state xuất hiện trong flow steps phải có node tương ứng trong diagram
+  - **CRITICAL**: flow steps dùng `PENDING_ACTIVATION` nhưng diagram chỉ có `PENDING_ISSUANCE` → dev không biết map vào đâu
+  - Xây danh sách states từ flow steps → đối chiếu với diagram nodes
+- Chú ý: đây khác với state_naming check (mục 1.2) vốn chỉ check naming pattern
+
+### 2.9 Referenced FR existence check (referenced_fr_exists)
+- Nếu SRS tham chiếu FR khác (VD: "cross-insurer fallback (FR29)", "see FR-15 for details"):
+  - FR được tham chiếu phải tồn tại trong danh sách FR đã định nghĩa trong project
+  - **HIGH**: tham chiếu FR không tồn tại → feature đó là out-of-scope thực chất, cần ghi rõ
+  - Cách check: extract tất cả FR references → đối chiếu với FR inventory (FR1–FR17 hoặc bất kỳ range nào project đang dùng)
+
+### 2.10 Technology stack alignment (tech_stack_consistent)
+- Database technology nhất quán cho cùng entity/module? (tech_stack_consistent)
+  - VD: MongoDB vs MariaDB vs PostgreSQL cho cùng entity → CRITICAL
+  - Message broker: Kafka vs RabbitMQ → phải nhất quán
+  - Cache: Redis vs Memcached → phải nhất quán
+- Thuật ngữ thống nhất, không dùng lẫn lộn? (terminology_consistent)
+  - VD: "Khách hàng" vs "Customer" vs "User" cho cùng concept
+
+### 2.11 Architecture alignment (MANDATORY via KG)
+
+**Token-efficient:** Read Architecture entity → find service catalog section → targeted read.
+
+1. From KG: read architecture entity `key_sections` to find "Service Catalog" or "Technology Stack" sections
+2. From upstream context: check service/component definitions in `.vsaf/docs/features/{feature-name}/03-adr.md` or `graphify-out/graph.json`
+3. Targeted read of architecture sections
+4. Compare:
+   - SRS tech stack (DB, framework, broker) matches architecture decisions?
+   - SRS API patterns match architecture API conventions?
+   - SRS service boundaries align with architecture service mapping?
+
+Item ID: `architecture_alignment`
+Scoring: 1.0 (aligned) / 0.75 (minor deviation) / 0.5 (significant mismatch) / 0.0 (contradicts)
+
+### 2.12 Architecture Service Boundary Check (C-2 — new check)
+
+**Zero extra token cost — pure Grep + KG lookup.**
+
+1. Load `arch_services` from `context.yaml` → list of valid service names (e.g., `ntbh-payment-service`, `ntbh-policy-service`)
+2. Run Grep `service_references` patterns from `{grepPatterns}` against `srs_path`:
+   - `service_name` pattern → find all service references in SRS flows/diagrams
+   - `infra_component` pattern → find Kafka, Redis, Keycloak, Kong references
+3. For each service name found in SRS:
+   - Is it in `arch_services` list? → OK
+   - Not in list → **CRITICAL: "SRS references non-existent service {name} — not in Architecture service catalog"**
+4. For each infra component found in SRS:
+   - Is it in the approved tech stack (from Architecture entity)? → OK
+   - Not approved → **HIGH: "Unapproved infrastructure component {name}"**
+
+Item ID: `architecture_alignment` (extends existing check in 2.11)
+
+### 2.13 Error Code Completeness Cross-check (C-3 — new check)
+
+**Zero extra token cost — pure Grep.**
+
+1. Grep Section 3 (error codes section, use `section_error_codes` line range from `section_index`):
+   - Extract all error code IDs defined in section 4
+2. For each error code ID, Grep full `srs_path` for that ID:
+   - Appears in at least one flow step → OK
+   - Never referenced in flows → MEDIUM: "Error code {ID} defined in Section 4 but never referenced in flow steps"
+3. Reverse check: Grep flow tables for any error code pattern not in Section 4:
+   - Referenced in flows but not defined → HIGH: "Error code {code} referenced in flows but not defined in Section 4"
+
+Item ID: `error_code_consistency` (enhances existing check)
+
+### 2.14 Upstream structural consistency (upstream_structural_consistency)
+
+**Complements all other cross-file checks in Section 2.**
+Those checks validate SRS ↔ System SRS and SRS ↔ Architecture for tech stack/service boundaries.
+This check validates SRS ↔ BRD/PRD for structural artifact consistency (state machines, entity schemas, events, API paths).
+
+**Zero extra reads:** Reuses BRD/PRD/Architecture sections already loaded by V-02 context or V-04's architecture checks. If context.yaml contains `kg.brd_key_sections` and `kg.prd_key_sections`, use those line ranges. Otherwise, this check is skipped (KG not available).
+
+#### Artifact Extraction
+
+> **Template note (2026-04):** S3 (Kafka event coverage), S4 (Entity field schema), S5 (API endpoint paths) đã bị xóa — những artifact này không còn trong SRS. Chỉ giữ S1, S2, S6 (state machine + AC state names).
+
+From upstream docs already in context, extract and compare against SRS:
+
+| # | Check | Upstream Source | SRS Source | Diff Type |
+|---|-------|----------------|------------|-----------|
+| S1 | State machine states | BRD PlantUML `state` declarations | SRS Section 8 PlantUML states | Set diff: additions, removals |
+| S2 | State transitions + order | BRD PlantUML `-->` arrows | SRS PlantUML `-->` arrows | Order comparison |
+| ~~S3~~ | ~~Kafka event coverage~~ | ~~REMOVED~~ | ~~REMOVED~~ | ~~REMOVED~~ |
+| ~~S4~~ | ~~Entity field schema~~ | ~~REMOVED~~ | ~~REMOVED~~ | ~~REMOVED~~ |
+| ~~S5~~ | ~~API endpoint paths~~ | ~~REMOVED~~ | ~~REMOVED~~ | ~~REMOVED~~ |
+| S6 | PRD AC state names | PRD AC text (`state_chain` pattern) | SRS canonical state names | Name alignment |
+
+#### Diff Logic (same for all artifact types)
+
+For each artifact type where both upstream and SRS have data:
+
+1. Extract `upstream_list` and `srs_list`
+2. Report:
+   - **In upstream, NOT in SRS** → severity depends on type:
+     - State/field dropped → CRITICAL
+     - Event not covered → HIGH
+     - API path missing → HIGH
+   - **In SRS, NOT in upstream** → typically OK (SRS refines), but flag if:
+     - Entirely new entity/state with no upstream trace → HIGH (possible invention)
+     - New API endpoint not in Architecture → MEDIUM
+   - **Same item, different name** → HIGH (naming inconsistency)
+   - **Same items, different order** → HIGH for transitions (logic change); LOW for fields (cosmetic)
+   - **Same field, different type** → HIGH (e.g., DECIMAL vs BIGINT)
+
+3. For each flagged item, include in finding:
+   - `upstream_source`: which doc and line
+   - `srs_source`: which section and line
+   - `diff_type`: addition | removal | rename | reorder | type_mismatch
+   - `severity`: per rules above
+   - `suggestion`: specific fix (e.g., "Align SRS state name to BRD: rename COMPLETED → PAID, or document the split in SRS changelog")
+
+#### Interaction with V-02 6e
+
+V-02 `upstream_artifact_alignment` checks business-level alignment (are the right things specified?).
+V-04 `upstream_structural_consistency` checks structural-level consistency (are they specified the same way?).
+
+Example: BRD says entity has field `claim_number` (VARCHAR 50). SRS has `claim_reference` (VARCHAR 50).
+- V-02 asks: "Is this the same business concept or a new field?" → Business alignment question
+- V-04 asks: "These are different field names for similar purpose — is naming consistent?" → Structural consistency question
+
+Both checks may flag the same artifact from different angles. This is intentional — they serve different reviewers (BA vs Dev/Architect).
+
+**Scoring:**
+- All structural artifacts consistent across upstream and SRS → 1.0
+- Minor: 1-2 naming variants with clear semantic equivalence → 0.75
+- Significant: field type mismatches, missing events, or >3 naming divergences → 0.5
+- Major: dropped upstream states/fields, reversed transitions → 0.25
+- Fundamental: SRS structure contradicts upstream (different entity, different lifecycle) → 0.0
+
+Item ID: `upstream_structural_consistency`
+
+---
+
+## 3. Ghi findings
+
+Format:
+```markdown
+| # | Severity | Dimension | File | Item ID | Score | Evidence | Suggestion | Business Impact | Source |
+```
+
+Each finding MUST include `business_impact` with three sub-fields:
+- **WHO**: Primary stakeholder affected (Dev, QA, PO, Ops, Customer)
+- **WHAT**: Impact type (Blocked, Rework risk, UX degradation, Compliance risk)
+- **WHEN**: When impact materializes (Before Sprint, During Sprint, After Release)
+```
+
+Ghi rõ file(s) liên quan khi cross-file: `file1 AND file2`
+
+---
+
+## 4. Tính Consistency dimension score
+
+```
+consistency_score = round(sum(item_scores.values()) / 19 × 100, 1)
+```
+
+Canonical item IDs (N = 19, fixed):
+`uc_id_pattern`, `screen_id_pattern`, `error_code_consistency`, `br_code_consistency`, `actor_naming`, `entity_naming`, `state_naming`, `screen_control_naming`, `activity_diagram_step_numbering`, `rtm_fr_match`, `api_naming_pattern`, `cross_file_state_machine_match`, `service_ownership_consistent`, `state_name_uc_vs_diagram`, `referenced_fr_exists`, `tech_stack_consistent`, `terminology_consistent`, `architecture_alignment`, `upstream_structural_consistency`
+
+⚠️ MANDATORY: N = 19 (fixed). N/A items → score = 1.0 (do not skip from denominator). No post-hoc calibration. dimension_score in YAML = formula result only.
+
+---
+
+## 5. Append findings vào report
+
+Append CRITICAL/HIGH → section "4. Critical & High Findings". Append MEDIUM/LOW → section "5. Medium & Low Findings".
+
+Update frontmatter: thêm `step-v-04-consistency` vào `stepsCompleted`.
+
+---
+
+## [NEW] Write Structured Findings
+
+Write file `{findingsOutput}`:
+```yaml
+# findings-consistency.yaml — generated by step-v-04
+# model: sonnet | weight: 1.0
+
+dimension: consistency
+weight: 1.0
+dimension_score: 0
+status: OK
+findings: []
+summary:
+  total: 0
+  critical: 0
+  high: 0
+  medium: 0
+  low: 0
+item_scores:
+  uc_id_pattern: 0.0
+  screen_id_pattern: 0.0
+  error_code_consistency: 0.0
+  br_code_consistency: 0.0
+  actor_naming: 0.0
+  entity_naming: 0.0
+  state_naming: 0.0
+  screen_control_naming: 0.0
+  activity_diagram_step_numbering: 0.0
+  rtm_fr_match: 0.0
+  api_naming_pattern: 0.0
+  cross_file_state_machine_match: 0.0
+  service_ownership_consistent: 0.0
+  state_name_uc_vs_diagram: 0.0
+  referenced_fr_exists: 0.0
+  tech_stack_consistent: 0.0
+  terminology_consistent: 0.0
+  architecture_alignment: 0.0
+  upstream_structural_consistency: 0.0
+new_checks:
+  service_boundary_violations: []   # list of unauthorized service references
+  orphan_error_codes: []            # error codes defined but never referenced
+  undefined_error_codes: []         # error codes referenced but not defined
+  orphan_br_ids: []                 # BR IDs defined but not referenced in flows
+  upstream_diffs: []   # list of {artifact_type, diff_type, upstream_source, upstream_value, srs_value, severity}
+```
+
+---
+
+## 6. Menu
+
+```
+Consistency Score: {X}% ({status})
+- CRITICAL: {count}
+- HIGH: {count}
+- MEDIUM: {count}
+- LOW: {count}
+
+[C] Continue — Sang Quality (Step V-05)
+[D] Detail — Xem chi tiết findings
+[X] Cancel
+```
+
+**Chờ user chọn.**
+
+Khi user chọn **C**: đọc fully và follow `./step-v-05-quality.md`

package/skills/sdlc/ba-validate-srs/steps-v/step-v-05-quality.md

@@ -0,0 +1,347 @@
+# Step V-05: Quality — Kiểm tra chất lượng nội dung
+
+---
+# model: haiku
+# findingsOutput: '{output_folder}/_validation_temp/findings-quality.yaml'
+# contextFile: '{output_folder}/_validation_temp/context.yaml'
+# grepPatterns: '../data/grep-patterns-srs.yaml'
+---
+
+## 0. Load Context and Patterns
+
+Read `{contextFile}` → get `srs_path`, `srs_section_index`, `uc_cache`.
+Read `{grepPatterns}` → load `vague_vietnamese`, `vague_english`, `ac_format`, `srs_structure`, `diagram_syntax` pattern groups.
+
+**ALL checks in this step use Grep tool. Do NOT use Read on the SRS file.**
+**Exception: Section 3 (cross-file duplicate detection) may use targeted Read.**
+
+---
+
+## 1. Ambiguous Language Check (Grep-only)
+
+Run Grep patterns from `vague_vietnamese` and `vague_english` groups against `srs_path`:
+- Each pattern: output_mode="content", -n=true to get line numbers
+- For each match, check context: is this in a BR/NFR/AC statement (flag) or a capability description (OK)?
+- Count flagged violations by category
+
+**Scoring (same as before):**
+- > 10 flagged → Score 0.0
+- 5–10 → Score 0.5
+- 1–4 → Score 0.75
+- 0 → Score 1.0
+
+Item ID: `no_ambiguous_language`
+
+---
+
+## 2. Acceptance Criteria Format Check (Grep-only)
+
+Run patterns from `ac_format` group against `srs_path`:
+- `gherkin_gwt` pattern → count GWT ACs
+- `vietnamese_conditional_ac` pattern → count Vietnamese-style ACs
+- `ac_id_pattern` → count AC IDs (confirms ACs are formally defined)
+
+Also check from `uc_cache` in context.yaml: count UCs → expected ≥ 1 AC per UC.
+
+**Scoring:** Same as before (GWT+measurable=1.0, AC no GWT=0.5, text only=0.25, none=0.0)
+
+Item ID: `acceptance_criteria_format`
+
+---
+
+## 3. Duplicate requirements check
+
+Tìm requirements trùng lặp:
+
+### 3.1 Intra-file
+- Cùng requirement xuất hiện ở nhiều UC trong 1 file?
+
+### 3.2 Cross-file (nếu batch/full)
+- Cùng requirement xuất hiện ở nhiều SRS files?
+- VD: Consent management overlap giữa FR-1 và FR-15
+
+**Nếu phát hiện overlap:**
+- Đánh giá mức độ: identical (0.0) vs complementary (0.75)
+- Gợi ý file nào nên own requirement
+
+Item ID: `no_duplicate_requirements`
+
+---
+
+## 4. Scope clarity check
+
+Kiểm tra mỗi SRS file có:
+
+- Section "Phạm vi chức năng" hoặc In-scope?
+- Section "Ngoài phạm vi" hoặc Out-of-scope?
+- Ranh giới rõ ràng với FRs liên quan?
+
+**Scoring:**
+- Có cả In + Out scope → 1.0
+- Có In scope nhưng thiếu Out scope → 0.5
+- Có "Flow liên quan" nhưng không explicit scope → 0.5
+- Không có gì → 0.0
+
+Item ID: `clear_scope`
+
+---
+
+## 5. Opaque rule check
+
+Kiểm tra các Business Rule và policy statements trong SRS:
+
+- Rule phải tự giải thích được mà không cần PO interpret. Dấu hiệu rule mơ hồ:
+  - Tham chiếu undefined term: "sensitive details not exposed until acceptance" — "acceptance" là event gì?
+  - Điều kiện không rõ ràng: "khi phù hợp", "tùy context", "nếu cần thiết"
+  - Rule thiếu subject: "không exposed" — ai không exposed? service nào? endpoint nào?
+- Mỗi rule mơ hồ → ghi finding với suggestion rewrite rõ ràng
+- Phân biệt với `no_ambiguous_language` (mục 1): mục này focus vào rule semantics, không chỉ từ vựng
+
+**Scoring:**
+- Tất cả rule self-explanatory → 1.0
+- 1-2 rule cần clarify nhỏ → 0.75
+- 3+ rule mơ hồ, hoặc 1 rule core không hiểu được → 0.5
+- Rule core hoàn toàn không interpret được → 0.0 (HIGH)
+
+Item ID: `rules_self_explanatory`
+
+---
+
+## 5b. Cross-Role Readability Check
+
+Kiểm tra requirement có thể hiểu giống nhau bởi BA, Dev, và QA không:
+
+**Dấu hiệu viết sai:**
+- Dùng thuật ngữ nghiệp vụ chưa được định nghĩa trong Glossary (section 1.2)
+- Câu có thể hiểu theo 2 cách tuỳ người đọc — VD: "hệ thống kiểm tra hợp lệ" → BA hiểu là validate UI, Dev hiểu là DB check, QA hiểu là API check
+- Subject không rõ — "sẽ gửi thông báo" → ai gửi? đến ai?
+- Điều kiện dạng "nếu cần" / "nếu phù hợp" → Dev và QA không thể ra testcase
+
+**Cách kiểm tra:**
+- Với mỗi UC step có hành động quan trọng (validate, send, update, check): subject + verb + object có đủ không?
+- Với mỗi business rule: trigger condition → action → result có viết đủ 3 phần không?
+- Có term nào trong flow tables không có trong Glossary? → flag để bổ sung
+
+**Scoring:**
+- Tất cả requirements rõ subject/verb/result, dùng term đã glossarized → 1.0
+- 1-3 steps có subject mơ hồ hoặc term chưa glossarize → 0.75
+- Nhiều steps thiếu subject/result rõ ràng → 0.5
+- Core flow steps không thể viết testcase vì quá mơ hồ → 0.25 (HIGH)
+
+Item ID: `cross_role_readability`
+
+---
+
+## 5c. Testability per Requirement
+
+Kiểm tra mỗi UC/AC có thể viết testcase độc lập không:
+
+- Mỗi AC có exactly 1 expected outcome cụ thể không?
+  - BAD: "hệ thống xử lý phù hợp" / "hệ thống phản hồi kịp thời"
+  - GOOD: "hệ thống trả HTTP 200 với body `{status: 'CREATED'}` trong < 2s"
+- Có AC nào kết quả phụ thuộc vào external state không rõ ràng không?
+  - VD: "nếu insurer accept" — điều kiện này có thể simulate trong test không?
+- Có UC nào không có AC hoặc chỉ có AC chung chung → không thể viết test → CRITICAL
+
+**Scoring:**
+- Tất cả AC có expected outcome rõ, testable → 1.0
+- Phần lớn rõ, 1-2 AC cần clarify expected result → 0.75
+- Nhiều AC thiếu expected result cụ thể → 0.5
+- AC chỉ describe behavior mà không có measurable outcome → 0.25 (HIGH)
+- Không có AC → 0.0 (CRITICAL)
+
+Item ID: `testability_per_requirement`
+
+---
+
+## 5d. Section Numbering Consistency (Grep-only)
+
+Kiểm tra heading số thứ tự nhất quán với cấu trúc template mới:
+
+**Template expected heading structure:**
+```
+## 1. Mô tả chung
+### 1.1 / 1.2 / 1.3
+## 2. Đặc tả Use Cases
+### 2.1 / 2.2 ...
+## 3. Danh sách mã lỗi
+## 4. Chức năng ảnh hưởng
+## 5. Business Rules
+## 6. Yêu cầu phi chức năng
+### 6.1 / 6.2 ... (not 7.1 / 7.2)
+## 7. Ràng buộc, Giả định & Phụ thuộc
+### 7.1 / 7.2 / 7.3 / 7.4 (not 8.1 / 8.2)
+## 8. State Diagrams
+## 9. Ma trận truy xuất
+```
+
+**Grep checks:**
+1. Grep `^### [78]\.\d` in srs_path → if found inside a `## 6.` section (NFR section) → MEDIUM: section 6 has wrong sub-headings
+2. Grep `^### [89]\.\d` in srs_path → if found inside a `## 7.` section → MEDIUM: section 7 has wrong sub-headings
+
+**Scoring:**
+- Không có heading mismatch → 1.0
+- 1 section có sub-heading dùng số section cha sai → 0.75 (MEDIUM finding)
+- Nhiều sections bị mismatch → 0.5
+
+Item ID: `section_numbering_consistent`
+
+---
+
+## 6. Flow Step Quality (Grep-only)
+
+- Grep `^\d+\.\s` in `srs_path` → check step numbering exists and is sequential
+- Grep `→ chuyển bước|→ kết thúc|→ hiển thị lỗi|→ bước` → verify steps have outcomes
+- Grep `Nhánh [A-Z]|Branch [A-Z]` → verify branching is explicit
+
+Item IDs: `flow_step_numbering`, `flow_clarity`, `branching`
+
+---
+
+## 6. Diagram Syntax Check (Grep-only)
+
+Run patterns from `diagram_syntax` group:
+- Count `@startuml` occurrences vs `@enduml` occurrences → must be equal
+- Grep `unfilled_placeholder_in_diagram` → any {{...}} still in diagrams? → CRITICAL
+
+Item ID: `diagram_syntax_valid`
+
+---
+
+## 6c. Atomicity Check (LLM analysis)
+
+Kiểm tra mỗi requirement/UC có chứa đúng 1 ý duy nhất — có thể dev/estimate/test độc lập:
+
+### 6c.1 Single Responsibility per UC
+
+- Mỗi UC title và scope có chỉ mô tả 1 hành vi duy nhất không?
+- **Dấu hiệu vi phạm:**
+  - Title dạng "Mua bảo hiểm và thanh toán và nhận HĐ" → compound UC, nên tách
+  - UC mô tả cả happy path lẫn admin flow trong cùng 1 UC → scope quá rộng
+  - UC vừa handle user action vừa xử lý background job cùng lúc
+
+**Item ID:** `requirement_single_responsibility`
+
+**Scoring:**
+- Tất cả UC có scope đơn → 1.0
+- 1-2 UC bị compound nhưng minor (dễ tách) → 0.75
+- Nhiều UC compound → 0.5
+- Core UC gộp nhiều flow không thể tách scope → 0.25 (HIGH)
+
+---
+
+### 6c.2 No Compound Requirements
+
+- Mỗi Business Rule, AC, hoặc NFR statement có chỉ phát biểu 1 điều kiện → 1 kết quả không?
+- **Dấu hiệu vi phạm:**
+  - "Hệ thống validate form **và** gửi email **và** cập nhật DB" trong 1 câu requirement
+  - BR dùng "đồng thời", "cùng lúc đó", "và cũng" → 2 hành vi trong 1 rule
+  - AC có nhiều `Then` cho 1 `When` → nên tách thành 2 AC
+
+**Item ID:** `no_compound_requirement`
+
+**Scoring:**
+- Tất cả BR/AC là single-statement → 1.0
+- Vài BR có 2 điều kiện nhưng logic liên quan chặt → 0.75
+- Nhiều BR/AC compound → 0.5
+- Core BR không thể phân tách rõ → 0.25
+
+---
+
+### 6c.3 Independently Estimable
+
+- Mỗi UC có thể được Dev estimate và implement mà không cần UC khác chưa done không?
+- **Dấu hiệu vi phạm:**
+  - UC A hardcode phụ thuộc UC B nhưng UC B chưa trong sprint
+  - UC A chỉ có ý nghĩa khi UC C cũng deploy cùng lúc → không thể ship độc lập
+  - UC giả định API từ service khác đã sẵn sàng nhưng không nêu dependency rõ
+
+**Lưu ý:** Có dependency ≠ vi phạm. Vi phạm là dependency KHÔNG ĐƯỢC GHI RÕ hoặc dependency chưa confirmed.
+
+**Item ID:** `independently_estimable`
+
+**Scoring:**
+- Tất cả UC hoặc có dependency ghi rõ (và confirmed) hoặc independent → 1.0
+- 1-2 UC có implied dependency chưa document → 0.75
+- Nhiều UC phụ thuộc chéo nhau không rõ → 0.5
+- Sprint không thể plan được vì UC entangled → 0.25 (HIGH)
+
+---
+
+## 7. Tính Quality dimension score
+
+```
+quality_score = round(sum(item_scores.values()) / 15 × 100, 1)
+```
+
+Canonical item IDs (N = 15, fixed):
+`no_ambiguous_language`, `acceptance_criteria_format`, `no_duplicate_requirements`, `clear_scope`, `rules_self_explanatory`, `cross_role_readability`, `testability_per_requirement`, `section_numbering_consistent`, `flow_step_numbering`, `flow_clarity`, `branching`, `diagram_syntax_valid`, `requirement_single_responsibility`, `no_compound_requirement`, `independently_estimable`
+
+⚠️ MANDATORY: N = 15 (fixed). N/A items → score = 1.0 (do not skip from denominator). No post-hoc calibration. dimension_score in YAML = formula result only.
+
+---
+
+## 8. Append findings vào report
+
+Append CRITICAL/HIGH → section "4. Critical & High Findings". Append MEDIUM/LOW → section "5. Medium & Low Findings".
+
+Update frontmatter: thêm `step-v-05-quality` vào `stepsCompleted`.
+
+---
+
+## [NEW] Write Structured Findings
+
+Write file `{findingsOutput}`:
+```yaml
+# findings-quality.yaml — generated by step-v-05
+# model: haiku | weight: 1.0
+
+dimension: quality
+weight: 1.0
+dimension_score: 0   # calculated: sum(scores)/count × 100
+status: OK           # OK | WARN | FAIL
+findings:
+  []  # list of {item_id, severity, score, evidence, suggestion, source}
+summary:
+  total: 0
+  critical: 0
+  high: 0
+  medium: 0
+  low: 0
+item_scores:
+  no_ambiguous_language: 0.0
+  acceptance_criteria_format: 0.0
+  no_duplicate_requirements: 0.0
+  clear_scope: 0.0
+  rules_self_explanatory: 0.0
+  cross_role_readability: 0.0
+  testability_per_requirement: 0.0
+  section_numbering_consistent: 0.0
+  flow_step_numbering: 0.0
+  flow_clarity: 0.0
+  branching: 0.0
+  diagram_syntax_valid: 0.0
+  requirement_single_responsibility: 0.0
+  no_compound_requirement: 0.0
+  independently_estimable: 0.0
+```
+
+---
+
+## 9. Menu
+
+```
+Quality Score: {X}% ({status})
+- CRITICAL: {count}
+- HIGH: {count}
+- MEDIUM: {count}
+- LOW: {count}
+
+[C] Continue — Sang System & NFR (Step V-06)
+[D] Detail — Xem chi tiết findings
+[X] Cancel
+```
+
+**Chờ user chọn.**
+
+Khi user chọn **C**: đọc fully và follow `./step-v-06-system-nfr.md`