@torus-engineering/tas-kit 1.9.0 → 1.11.1

package/.claude/commands/tas-story.md

@@ -1,91 +1,91 @@
-# /tas-story $ARGUMENTS
-
-Vai trò: PE - Product Engineer
-Tạo mới hoặc cập nhật User Story document.
-
-**Phạm vi:** Nghiệp vụ, trải nghiệm người dùng, acceptance criteria, test cases.
-**Không thuộc phạm vi:** Kỹ thuật implement, files cần sửa, database schema — đó là việc của `/tas-plan`.
-
-## Always / Ask / Never
-
-| | Hành động |
-|---|---|
-| **Always** | Viết AC dạng Given/When/Then |
-| **Always** | Set `plan_status: pending` cho Story mới |
-| **Ask** | Khi Story > 8h — gợi ý tách nhỏ |
-| **Never** | Đọc SAD, ADR — kỹ thuật là việc của `/tas-plan` |
-
-## Prerequisite
-- Ít nhất một Feature phải tồn tại
-
-## Hành động
-
-### Chế độ CREATE ($ARGUMENTS là mô tả Story mới, hoặc không có $ARGUMENTS)
-
-**Bước 1 — Xác định Feature**
-- Đọc `project.code` từ root/`tas.yaml`
-- Ưu tiên theo thứ tự:
-  1. Nếu `$ARGUMENTS` chứa Feature ID → dùng luôn
-  2. Nếu context có `parent_id` → dùng luôn
-  3. Hỏi user: "Story này thuộc Feature nào?" — không quét thư mục
-
-**Bước 2 — Thu thập context nghiệp vụ**
-- Đọc file Feature đã xác định (lấy business context, scope, danh sách Stories hiện có)
-- Đọc PRD (nếu có) — chỉ lấy business requirements, user goals
-
-**Bước 3 — Xác định Story ID**
-- Đọc section Stories trong Feature file → xác định index tiếp theo từ danh sách đó
-- KHÔNG quét thư mục
-
-**Bước 4 — Soạn Story với user**
-
-Thảo luận để điền đầy đủ:
-
-a) **User Story**: "As a [role], I want [goal], so that [benefit]"
-
-b) **Business Requirements** (nếu có): business rules đặc thù, constraints từ stakeholders
-
-c) **Design Notes** (nếu có): UI/UX specs, mockup links, flow diagrams
-
-d) **Prerequisites** (nếu có): Stories khác phải done trước
-
-e) **Acceptance Criteria**: mỗi AC một kịch bản Given/When/Then rõ ràng
-
-**Bước 5 — Test Case Prompting**
-
-Sau khi AC được xác nhận, hỏi thêm:
-- "Ngoài happy path, có edge case nào cần test không?" (input rỗng, giá trị biên, concurrent)
-- "Có negative case nào cần cover?" (unauthorized, invalid data, timeout, not found)
-- "Có external dependency nào cần mock khi test?" (API bên ngoài, database state)
-
-Ghi tất cả vào section `## Unit Test Cases`.
-
-**Bước 6 — Tạo file**
-- Đọc `.tas/templates/Story.md` để lấy format
-- Tạo `docs/epics/{code}-Epic-{NNN}-{slug}/{code}-Feature-{NNN}-{slug}/{code}-Story-{NNN}-{slug}.md`
-- Frontmatter: `plan_status: pending`, `plan_date:` để trống
-
-**Bước 7 — Cập nhật project-status.yaml**
-Theo `.claude/rules/common/project-status.md` — thêm entry vào `epics.{EPIC_ID}.features.{FEATURE_ID}.stories`.
-
-**Bước 8 — Thông báo next step**
-> "Story đã tạo. Trước khi SE bắt đầu code, cần chạy `/tas-plan {Story-ID}` để lập kế hoạch kỹ thuật."
-
----
-
-### Chế độ UPDATE ($ARGUMENTS là Story ID, ví dụ: "Story-005")
-
-1. Tìm file qua glob `docs/epics/**/{code}-Story-{ID}-*.md`
-2. Đọc file Story hiện tại
-3. Hỏi user cần thay đổi gì (cập nhật AC, đổi status, thêm test cases, sửa business rule...)
-4. Cập nhật file, thêm entry vào Changelog
-5. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md`.
-
-## Nguyên tắc
-- Story phải đủ nhỏ để hoàn thành trong **4-8 giờ**; nếu lớn hơn → tách thành nhiều Stories
-- Story file = **product artifact**: mô tả *what* và *why*, không phải *how*
-- Story status: New → Committed → In Progress → Deploy Test → Verify Test → Deploy Stag → Verify Stag → Deploy Prod → Verify Prod → Done
-
-## Bước cuối — Token Log
-
-Invoke skill `token-logger`: ghi AI Usage Log vào file Story đang làm việc.
+# /tas-story $ARGUMENTS
+
+Role: PE - Product Engineer
+Create or update User Story document.
+
+**Scope:** Business logic, user experience, acceptance criteria, test cases.
+**Out of scope:** Technical implementation, files to modify, database schema — that's `/tas-plan`'s job.
+
+## Always / Ask / Never
+
+| | Action |
+|---|---|
+| **Always** | Write AC in Given/When/Then format |
+| **Always** | Set `plan_status: pending` for new Story |
+| **Ask** | When Story > 8h — suggest splitting |
+| **Never** | Read SAD, ADR — technical is `/tas-plan`'s job |
+
+## Prerequisite
+- At least one Feature must exist
+
+## Actions
+
+### CREATE mode ($ARGUMENTS is new Story description, or no $ARGUMENTS)
+
+**Step 1 — Identify Feature**
+- Read `project.code` from root/`tas.yaml`
+- Prioritize in order:
+  1. If `$ARGUMENTS` contains Feature ID → use it
+  2. If context has `parent_id` → use it
+  3. Ask user: "Which Feature does this Story belong to?" — no directory scan
+
+**Step 2 — Gather business context**
+- Read identified Feature file (get business context, scope, existing Stories list)
+- Read PRD (if exists) — only business requirements, user goals
+
+**Step 3 — Determine Story ID**
+- Read Stories section in Feature file → determine next index from that list
+- DO NOT scan directory
+
+**Step 4 — Draft Story with user**
+
+Discuss to fill in:
+
+a) **User Story**: "As a [role], I want [goal], so that [benefit]"
+
+b) **Business Requirements** (if any): specific business rules, stakeholder constraints
+
+c) **Design Notes** (if any): UI/UX specs, mockup links, flow diagrams
+
+d) **Prerequisites** (if any): other Stories that must be done first
+
+e) **Acceptance Criteria**: each AC is a clear Given/When/Then scenario
+
+**Step 5 — Test Case Prompting**
+
+After AC confirmed, ask more:
+- "Besides happy path, any edge cases to test?" (empty input, boundary values, concurrent)
+- "Any negative cases to cover?" (unauthorized, invalid data, timeout, not found)
+- "Any external dependencies to mock when testing?" (external APIs, database state)
+
+Write all to `## Unit Test Cases` section.
+
+**Step 6 — Create file**
+- Read `.tas/templates/Story.md` for format
+- Create `docs/epics/{code}-Epic-{NNN}-{slug}/{code}-Feature-{NNN}-{slug}/{code}-Story-{NNN}-{slug}.md`
+- Frontmatter: `plan_status: pending`, `plan_date:` left empty
+
+**Step 7 — Update project-status.yaml**
+Per `.claude/rules/common/project-status.md` — add entry to `epics.{EPIC_ID}.features.{FEATURE_ID}.stories`.
+
+**Step 8 — Notify next step**
+> "Story created. Before SE starts coding, run `/tas-plan {Story-ID}` for technical planning."
+
+---
+
+### UPDATE mode ($ARGUMENTS is Story ID, e.g., "Story-005")
+
+1. Find file via glob `docs/epics/**/{code}-Story-{ID}-*.md`
+2. Read current Story file
+3. Ask user what needs changing (update AC, change status, add test cases, fix business rule...)
+4. Update file, add entry to Changelog
+5. Update `project-status.yaml` per `.claude/rules/common/project-status.md`.
+
+## Principles
+- Story must be small enough to complete in **4-8 hours**; if larger → split into multiple Stories
+- Story file = **product artifact**: describes *what* and *why*, not *how*
+- Story status: New → Committed → In Progress → Deploy Test → Verify Test → Deploy Stag → Verify Stag → Deploy Prod → Verify Prod → Done
+
+## Final Step — Token Log
+
+Invoke skill `token-logger`: write AI Usage Log to working Story file.

package/.claude/commands/tas-verify.md

@@ -1,51 +1,51 @@
-# /tas-verify $ARGUMENTS
-
-Vai trò: PE - Product Engineer
-Verify Feature trên môi trường Staging (Phase 2).
-
-## Prerequisite
-- Feature phải có status "Ready To Verify"
-- Môi trường Staging phải sẵn sàng
-
-## Hành động
-1. Cần context từ root/tas.yaml
-2. $ARGUMENTS là Feature ID. Nếu không có, liệt kê features có status "Ready To Verify".
-3. Tìm file Feature trong cây docs/epics/ (dùng glob)
-4. Cần context từ file Feature hiện tại (đặc biệt section Integration Test Cases và E2E Test Cases)
-
-### Workflow verify:
-4.5. **Chạy Automated Tests** (nếu có):
-
-   **Functional Tests** (Layer 2):
-   - Kiểm tra `docs/epics/{epic-dir}/{feature-dir}/Func-Test-*.md` đã có chưa
-   - Nếu có, hỏi PE: "Chạy functional test suite? Command: `yarn functest:mobile:{feature-slug}` (hoặc `yarn functest:web:{feature-slug}`)"
-   - Ghi nhận pass/fail của func suite
-
-   **E2E Tests** (Layer 3 - nếu Feature có E2E / Acceptance Test Cases):
-   > Launch `e2e-runner`: E2E verification cho Feature {ID}.
-   > Đọc section `## E2E / Acceptance Test Cases` từ Feature file — list từng test case.
-   > Chạy các test cases đó, báo cáo kết quả: Pass/Fail per test case với lý do nếu Fail.
-   > Không tự động fix lỗi — chỉ báo cáo kết quả để PE xác nhận.
-
-5. **Tổng hợp kết quả và xác nhận với PE**:
-   - Hiển thị summary automated test results (Functional + E2E)
-   - Hỏi PE: "Automated tests đã pass. Trên Staging thực có vấn đề nào mà automated tests không catch được không? (UX, business logic, edge case thực tế...)"
-
-6. Với mỗi issue PE báo cáo hoặc test case FAIL:
-   - Hỏi PE mô tả lỗi
-   - Tự động tạo Bug trong thư mục Feature đó (dùng logic /tas-bug)
-   - Bug có reference đến test case gốc (FT ID hoặc E2E ID), hoặc ghi rõ "phát hiện qua manual verify Staging"
-7. Cập nhật file Feature:
-   - Ghi kết quả test (Pass/Fail + ngày) vào từng test case
-   - Nếu tất cả Pass: cập nhật Feature status thành "Verified"
-   - Nếu có Fail: giữ Feature status "Ready To Verify", liệt kê bugs
-8. Cập nhật root/project-status.yaml
-
-## Nguyên tắc
-- KHÔNG skip test case nào, phải verify hết
-- Bug phát hiện ở Phase 2 PHẢI được ghi thành Bug để track
-- Feature chỉ được chuyển sang Phase 3 (Deploy) khi status = "Verified"
-
-## Bước cuối — Token Log
-
-Invoke skill `token-logger`: ghi AI Usage Log vào file Feature đang verify.
+# /tas-verify $ARGUMENTS
+
+Role: PE - Product Engineer
+Verify Feature on Staging environment (Phase 2).
+
+## Prerequisite
+- Feature must have status "Ready To Verify"
+- Staging environment must be ready
+
+## Actions
+1. Need context from root/tas.yaml
+2. $ARGUMENTS is Feature ID. If not provided, list features with status "Ready To Verify".
+3. Find Feature file in docs/epics/ tree (using glob)
+4. Need context from current Feature file (especially Integration Test Cases and E2E Test Cases sections)
+
+### Verification workflow:
+4.5. **Run Automated Tests** (if available):
+
+   **Functional Tests** (Layer 2):
+   - Check if `docs/epics/{epic-dir}/{feature-dir}/Func-Test-*.md` exists
+   - If yes, ask PE: "Run functional test suite? Command: `yarn functest:mobile:{feature-slug}` (or `yarn functest:web:{feature-slug}`)"
+   - Note pass/fail of func suite
+
+   **E2E Tests** (Layer 3 - if Feature has E2E / Acceptance Test Cases):
+   > Launch `e2e-runner`: E2E verification for Feature {ID}.
+   > Read `## E2E / Acceptance Test Cases` section from Feature file — list each test case.
+   > Run those test cases, report results: Pass/Fail per test case with reason if Fail.
+   > Don't auto-fix bugs — only report results for PE confirmation.
+
+5. **Synthesize results and confirm with PE**:
+   - Display automated test results summary (Functional + E2E)
+   - Ask PE: "Automated tests passed. Any issues on actual Staging that automated tests didn't catch? (UX, business logic, real-world edge cases...)"
+
+6. For each issue PE reports or test case FAIL:
+   - Ask PE to describe the bug
+   - Automatically create Bug in that Feature directory (use /tas-bug logic)
+   - Bug references original test case (FT ID or E2E ID), or notes "found via manual Staging verify"
+7. Update Feature file:
+   - Write test results (Pass/Fail + date) to each test case
+   - If all Pass: update Feature status to "Verified"
+   - If any Fail: keep Feature status "Ready To Verify", list bugs
+8. Update root/project-status.yaml
+
+## Principles
+- DO NOT skip any test case, must verify all
+- Bugs found in Phase 2 MUST be recorded as Bug for tracking
+- Feature only moves to Phase 3 (Deploy) when status = "Verified"
+
+## Final Step — Token Log
+
+Invoke skill `token-logger`: write AI Usage Log to Feature file being verified.

package/.claude/rules/common/post-review-agent.md

@@ -1,49 +1,49 @@
-# Post-Implementation Review (Isolated Agent)
-
-Sau khi implement hoặc fix xong, chạy review qua **Agent độc lập** — không dùng session hiện tại để tránh reviewer bias từ quá trình implement.
-
-## Cách dùng
-
-Gọi `Agent` tool với prompt sau (thay thế các placeholder `{}`):
-
-```
-Bạn là code reviewer. Không có context từ session trước — hãy review hoàn toàn khách quan.
-
-Artifact: {path-to-artifact-file}
-Changed files: {danh sách files vừa thay đổi}
-Stack: {stack từ CLAUDE.md}
-
-Thực hiện:
-1. Hygiene scan: debug code còn sót (console.log, debugger, print), secrets hardcoded,
-   commented-out blocks lớn (>5 dòng).
-1b. Silent failure scan — tìm các pattern sau:
-   - Swallowed exceptions: empty catch {}, catch chỉ log nhưng tiếp tục chạy như không có lỗi
-   - Silent async failures: fire-and-forget (unawaited task/Promise), async void (.NET),
-     .catch(() => {}) không xử lý gì
-   - Null blindspots: .FirstOrDefault() dùng trực tiếp không null-check (.NET),
-     optional chaining thiếu trên deeply nested object access (TS/JS),
-     dict.get() result dùng như non-None (Python)
-   - Error propagation sai: HTTP calls không check status trước khi parse,
-     hàm return bool/null khi lỗi thay vì throw (caller bỏ qua kết quả)
-   - Config reads không check existence
-2. Chạy tests: detect test runner (package.json → npm test / *.csproj → dotnet test /
-   pytest.ini → python -m pytest), report kết quả.
-3. Parallel review — launch đồng thời:
-   - code-reviewer: đọc .tas/checklists/code-review.md + .claude/rules/common/code-review.md.
-     Tập trung: naming, architecture, error handling, DRY, function size, nesting depth.
-   - security-reviewer: đọc .claude/rules/common/security.md.
-     Tập trung: OWASP Top 10, injection, hardcoded secrets, auth/authz.
-   - {lang_agent}: đọc .claude/rules/[stack]/coding-style.md + .claude/rules/[stack]/patterns.md.
-     Tập trung: async/await, null handling, type safety, anti-patterns của stack.
-4. Tổng hợp findings: Critical / High / Medium / Low với file:line và fix cụ thể.
-
-Trả về Review Summary đầy đủ.
-```
-
-## Gate Rule
-
-| Kết quả | Hành động |
-|---|---|
-| Có **Critical** hoặc **High** | List findings, **DỪNG**, yêu cầu fix trước khi tiếp tục |
-| Chỉ có **Medium** / **Low** | List gợi ý, hỏi user có muốn fix không, sau đó tiếp tục |
-| Không có findings | Tiếp tục bình thường |
+# Post-Implementation Review (Isolated Agent)
+
+After implementing or fixing, run review through **independent Agent** — don't use current session to avoid reviewer bias from implementation process.
+
+## How to use
+
+Call `Agent` tool with following prompt (replace placeholders `{}`):
+
+```
+You are code reviewer. No context from previous session — review completely objectively.
+
+Artifact: {path-to-artifact-file}
+Changed files: {list of files just changed}
+Stack: {stack from CLAUDE.md}
+
+Execute:
+1. Hygiene scan: leftover debug code (console.log, debugger, print), hardcoded secrets,
+   large commented-out blocks (>5 lines).
+1b. Silent failure scan — find following patterns:
+   - Swallowed exceptions: empty catch {}, catch only logs but continues like no error
+   - Silent async failures: fire-and-forget (unawaited task/Promise), async void (.NET),
+     .catch(() => {}) with no handling
+   - Null blindspots: .FirstOrDefault() used directly without null-check (.NET),
+     missing optional chaining on deeply nested object access (TS/JS),
+     dict.get() result used as non-None (Python)
+   - Error propagation wrong: HTTP calls don't check status before parse,
+     function returns bool/null when error instead of throwing (caller ignores result)
+   - Config reads don't check existence
+2. Run tests: detect test runner (package.json → npm test / *.csproj → dotnet test /
+   pytest.ini → python -m pytest), report results.
+3. Parallel review — launch simultaneously:
+   - code-reviewer: read .tas/checklists/code-review.md + .claude/rules/common/code-review.md.
+     Focus: naming, architecture, error handling, DRY, function size, nesting depth.
+   - security-reviewer: read .claude/rules/common/security.md.
+     Focus: OWASP Top 10, injection, hardcoded secrets, auth/authz.
+   - {lang_agent}: read .claude/rules/[stack]/coding-style.md + .claude/rules/[stack]/patterns.md.
+     Focus: async/await, null handling, type safety, stack-specific anti-patterns.
+4. Synthesize findings: Critical / High / Medium / Low with file:line and specific fix.
+
+Return full Review Summary.
+```
+
+## Gate Rule
+
+| Result | Action |
+|---|---|
+| Has **Critical** or **High** | List findings, **STOP**, require fix before continuing |
+| Only **Medium** / **Low** | List suggestions, ask if user wants to fix, then continue |
+| No findings | Continue normally |

package/.claude/rules/common/project-status.md

@@ -1,17 +1,17 @@
 # project-status.yaml — Update Convention
 
-File `project-status.yaml` ở project root là index tổng hợp trạng thái dự án.
-Commands cập nhật file này sau mỗi thay đổi artifact hoặc status.
+File `project-status.yaml` at project root is aggregate index of project status.
+Commands update this file after each artifact or status change.
 
-## Luôn cập nhật
+## Always update
 
 ```yaml
-last_updated: YYYY-MM-DD   # ngày hiện tại, mỗi lần có thay đổi
+last_updated: YYYY-MM-DD   # current date, each time there's a change
 ```
 
-## Artifacts (docs đơn lẻ)
+## Artifacts (individual docs)
 
-Cập nhật khi tạo mới hoặc thay đổi version:
+Update when creating new or changing version:
 
 ```yaml
 artifacts:
@@ -19,8 +19,8 @@ artifacts:
     file: docs/prd.md
     status: Draft | Review | Approved
     last_updated: YYYY-MM-DD
-    version: "1.0"           # tăng minor khi update nội dung, major khi thay đổi lớn
-    requirements_count: N    # chỉ dành cho PRD — đếm số FR-xxx
+    version: "1.0"           # increment minor when updating content, major for large changes
+    requirements_count: N    # only for PRD — count of FR-xxx
 
   sad:
     file: docs/sad.md
@@ -42,7 +42,7 @@ artifacts:
 
 ## Epics / Features / Stories
 
-Cập nhật khi tạo mới hoặc status thay đổi:
+Update when creating new or changing status:
 
 ```yaml
 epics:
@@ -72,9 +72,9 @@ adrs:
     title: "..."
 ```
 
-## Quy tắc
+## Rules
 
-- Chỉ cập nhật key liên quan đến thay đổi vừa xảy ra — không rewrite toàn bộ file
-- Nếu key chưa tồn tại: thêm mới
-- Nếu key đã tồn tại: cập nhật giá trị
-- Version: minor (+0.1) khi update nội dung; major (+1.0) khi thay đổi cấu trúc lớn
+- Only update key related to change just occurred — don't rewrite entire file
+- If key doesn't exist yet: add new
+- If key exists: update value
+- Version: minor (+0.1) when updating content; major (+1.0) when large structure change

package/.claude/rules/common/stack-detection.md

@@ -1,25 +1,25 @@
 # Stack Detection
 
-Đọc `CLAUDE.md` tại root, tìm section `## Tech Stack`, xác định các biến sau để dùng trong agent prompts và rule file lookups.
+Read `CLAUDE.md` at root, find `## Tech Stack` section, determine following variables for use in agent prompts and rule file lookups.
 
 ## lang_agent — Backend
 
-| Tech Stack chứa | lang_agent |
+| Tech Stack contains | lang_agent |
 |---|---|
 | `.NET` / `C#` | `csharp-reviewer` |
 | `Node.js` / `TypeScript` / `NestJS` / `Express` | `typescript-reviewer` |
 | `Python` / `FastAPI` / `Django` / `Flask` | `python-reviewer` |
 
-**Frontend bổ sung:** nếu Tech Stack chứa `React` → thêm `typescript-reviewer` vào lang_agent (nếu chưa có).
+**Frontend addition:** if Tech Stack contains `React` → add `typescript-reviewer` to lang_agent (if not already).
 
-## infra_agent và db_agent — Tùy chọn
+## infra_agent and db_agent — Optional
 
-| Tech Stack chứa | Biến | Value |
+| Tech Stack contains | Variable | Value |
 |---|---|---|
 | `AWS` (Infrastructure) | `infra_agent` | `aws-reviewer` |
 | `MySQL` / `PostgreSQL` / `MSSQL` / `SQL Server` / `SQLite` | `db_agent` | `database-reviewer` |
 
-## Rules directory theo stack
+## Rules directory by stack
 
 | lang_agent | Rules directory |
 |---|---|

package/.claude/rules/common/token-logging.md

@@ -1,27 +1,27 @@
-# Token Usage Logging
-
-Ghi `## AI Usage Log` vào cuối artifact file khi TAS command hoàn thành.
-
-## Token Estimation
-
-Ước tính từ session awareness: số ký tự mỗi file đã `Read` ÷ 4 ≈ tokens (English/code), ÷ 2 (Vietnamese).
-Số ký tự output artifact ÷ 4. Luôn append `(est.)`. User verify bằng `/cost` (CLI) hoặc `/context` (Desktop app).
-
-## Format
-
-```markdown
----
-
-## AI Usage Log
-
-| # | Date | Command | Input (est.) | Output (est.) |
-|---|------|---------|-------------|---------------|
-| 1 | YYYY-MM-DD | /tas-{name} | ~{N}k | ~{N}k |
-| 2 | YYYY-MM-DD | /tas-{name} (revision) | ~{N}k | ~{N}k |
-| **Total** | | | **~{N}k** | **~{N}k** |
-```
-
-## Update Rules
-
-- **Lần đầu**: section chưa tồn tại → append toàn bộ section với row đầu tiên và row Total
-- **Lần sau**: append row mới trước row Total, cập nhật Total (cộng dồn)
+# Token Usage Logging
+
+Write `## AI Usage Log` at end of artifact file when TAS command completes.
+
+## Token Estimation
+
+Estimate from session awareness: character count of each file `Read` ÷ 4 ≈ tokens (English/code), ÷ 2 (Vietnamese).
+Character count of artifact output ÷ 4. Always append `(est.)`. User verifies with `/cost` (CLI) or `/context` (Desktop app).
+
+## Format
+
+```markdown
+---
+
+## AI Usage Log
+
+| # | Date | Command | Input (est.) | Output (est.) |
+|---|------|---------|-------------|---------------|
+| 1 | YYYY-MM-DD | /tas-{name} | ~{N}k | ~{N}k |
+| 2 | YYYY-MM-DD | /tas-{name} (revision) | ~{N}k | ~{N}k |
+| **Total** | | | **~{N}k** | **~{N}k** |
+```
+
+## Update Rules
+
+- **First time**: section doesn't exist → append entire section with first row and Total row
+- **Subsequent**: append new row before Total row, update Total (cumulative)