sdtk-kit 0.3.0

package/assets/toolkit/toolkit/skills/sdtk-pm/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: sdtk-pm
+description: Product Manager + meta-orchestrator workflow for SDTK. Use when you need to start a new feature (Phase 1) or produce PM planning artifacts (PRD + BACKLOG) and update SHARED_PLANNING.md / QUALITY_CHECKLIST.md with correct phase handoffs.
+---
+
+# SDTK PM (Entry Point + Planning)
+
+## Outputs
+- Phase 1: `docs/product/PROJECT_INITIATION_[FEATURE_KEY].md`
+- Phase 2+ (after BA spec): `docs/product/PRD_[FEATURE_KEY].md` + `docs/product/BACKLOG_[FEATURE_KEY].md`
+
+## Process
+1. Confirm `FEATURE_KEY` + `FEATURE_NAME` + Phase-1 scope in/out.
+2. Create/update PM artifact(s) using `toolkit/templates/docs/product/*` as structure.
+3. Ensure REQ-xx list is clear and testable.
+4. If requirements are provided in VI/JP: keep the original text in an appendix and add an EN translation (literal) for traceability.
+5. Update `SHARED_PLANNING.md` + `QUALITY_CHECKLIST.md`.
+6. Handoff:
+   - After Project Initiation -> `@ba please analyze ...`
+   - After PRD/Backlog -> `@arch please design ...`
+
+## Clarification And Decisions (PM responsibility)
+- Collect OQ-xx items raised by BA/ARCH/DEV/QA in their respective artifacts.
+- Try to resolve OQ-xx using existing docs and reasonable product/tech decisions.
+- If still missing information from the original input: ask the user (final stakeholder) and record the answer as the resolution.
+- Record decisions in PRD `Decision Log` and update OQ-xx `Resolution` fields in the originating docs.

package/assets/toolkit/toolkit/skills/sdtk-qa/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: sdtk-qa
+description: QA workflow for SDTK. Use when you need to validate an implemented feature against BA/PRD/Backlog, run quality gates, document defects, and produce a QA_RELEASE_REPORT with a release decision.
+---
+
+# SDTK QA (Testing + Release Decision)
+
+## Output
+- `docs/qa/QA_RELEASE_REPORT_[FEATURE_KEY].md`
+- Optional (when detailed test design spec is requested):
+  - `docs/qa/[FEATURE_KEY]_TEST_CASE.md` via `sdtk-test-case-spec`
+
+## Process
+1. Validate prerequisites: DEV phase completed + code review PASS.
+2. Create test strategy mapped to UC/AC.
+3. If test-case specification artifact is required, invoke `sdtk-test-case-spec` and align counts/coverage with release testing scope.
+4. If acceptance criteria / expected behavior is unclear: record OQ-xx in QA report and escalate to `@pm` (PM asks the user if still missing info).
+5. Execute/record results (unit/integration/e2e as applicable).
+6. Record defects with severity and status.
+7. Decide: APPROVED vs REJECTED (with reasons).
+8. Update shared state + Phase 5 checklist.
+9. Handoff: `@pm please finalize release status ...` if approved.

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: sdtk-screen-design-spec
+description: Create/update screen flow-action specifications from requirement sources (Excel/Figma/spec docs), including screen flow PlantUML, UI item/action tables, API mapping tables, and screen-to-API traceability.
+---
+
+# SDTK Screen Flow Action Spec
+
+## Outputs
+- `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`
+- Optional supporting docs:
+  - `docs/specs/[FEATURE_KEY]_FIGMA_LAYOUT.md`
+  - `docs/specs/[FEATURE_KEY]_DESIGN_SPEC_FROM_EXCEL.md`
+  - `docs/specs/assets/[feature_snake]/screens/*`
+
+## Required Inputs
+- Feature key/name
+- Primary requirement sources (BA spec, architecture, customer design docs)
+- Screen source references (Figma URLs and/or requirement screenshots)
+- API endpoint source (`docs/api/[FEATURE_KEY]_ENDPOINTS.md`) when available
+
+## Process
+1. Read requirement sources and identify in-scope screens, dialogs, and transitions.
+2. Read and apply rules from `./references/FLOW_ACTION_SPEC_CREATION_RULES.md`.
+3. Build/update section `Feature overview` and `Screen flow action` (PlantUML).
+4. For each screen/dialog:
+   - Add metadata (screen ID, source link)
+   - Add screen image reference
+   - Add UI item/action table with `No` column
+   - Add API mapping table (trigger -> API -> data usage)
+5. Build/update `System processing flow` from use-case and process sources.
+6. Build/update `Open questions` for unresolved behavior/API/data points.
+7. Build/update `Screen - API Mapping` summary section.
+8. Validate:
+   - global numbering consistency (no screen-level reset)
+   - no broken image paths
+   - PlantUML renderability
+   - consistency with API endpoints spec
+   - EN artifact hygiene (no VI leftovers, no mojibake, no merged heading lines)
+   - for legacy specs with per-screen reset numbering: run renumber migration first
+9. Update document history and handoff to ARCH/DEV.
+
+## Rule References
+- Core rules: `./references/FLOW_ACTION_SPEC_CREATION_RULES.md`
+- Numbering reference: `./references/numbering-rules.md`
+- Figma reference: `./references/figma-mcp.md`
+- Excel image export reference: `./references/excel-image-export.md`
+
+## Validation Script
+- `scripts/validate_flow_action_spec_numbering.py`
+  - Checks duplicate/resetted numbering in action tables.
+  - Checks encoding/markdown hygiene.
+  - For EN artifacts, run with `--en-check`:
+    - `python "toolkit/skills/sdtk-screen-design-spec/scripts/validate_flow_action_spec_numbering.py" --spec "docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md" --en-check`
+- `scripts/renumber_flow_action_spec_global.py`
+  - Auto-migrates action table `No` fields to global numbering.
+  - Dry-run:
+    - `python "toolkit/skills/sdtk-screen-design-spec/scripts/renumber_flow_action_spec_global.py" --spec "docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md"`
+  - Apply:
+    - `python "toolkit/skills/sdtk-screen-design-spec/scripts/renumber_flow_action_spec_global.py" --spec "docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md" --write`

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/references/FLOW_ACTION_SPEC_CREATION_RULES.md

@@ -0,0 +1,136 @@
+# Flow Action Spec Creation Rules for AI Agents
+
+This document defines reusable rules for creating and updating screen flow-action specifications
+(for example `docs/specs/*_FLOW_ACTION_SPEC.md`).
+
+## 1. Scope and Goal
+
+- Produce a screen-level specification that is traceable from BA/ARCH to FE/BE implementation.
+- Keep one source of truth for:
+  - screen flow
+  - UI items and actions
+  - API calls per action
+  - screen-to-API mapping
+- Keep documentation implementation-aware and review-friendly.
+
+## 2. Mandatory Document Structure
+
+A flow-action spec should include, at minimum:
+
+1. `Abbreviations`
+2. `Feature overview`
+3. `Screen flow action` (with PlantUML)
+4. `Screen layout spec by flow action`
+5. `System processing flow`
+6. `Open questions`
+7. `Screen - API mapping`
+8. `Document history`
+
+If a section is not in scope, keep the section and mark explicitly as `N/A` with reason.
+
+## 3. Table Standards
+
+- Every table must include a `No` column (sequential numbering).
+- Use stable headers for action tables:
+  - `No | JP Item Name | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note`
+- Use stable headers for API mapping tables:
+  - `No | Trigger/When | UI item (No / JP Item Name) | API to call | Data usage / Notes`
+- Use stable headers for screen mapping:
+  - `No | Screen (section) | Screen ID | Read/Search APIs | Write APIs | Notes / Q&A refs`
+- Table rows must keep column count consistent with the header (no broken or merged rows).
+- Avoid single-line merged content that collapses multiple logical items into one table row.
+
+### 3.1 Language and Encoding Standards (EN Artifacts)
+
+- For EN artifacts (`docs/en/**` or explicitly requested EN version), narrative text must be English.
+- JP labels can remain only in JP-specific fields/columns (`JP Item Name`, `項目名`, source captions).
+- Do not leave mixed-language fragments in one sentence/cell (for example VI+EN mixed text).
+- If original VI/JP text is required for traceability, keep it in a clearly marked appendix block (`Original Text`), then provide EN translation.
+- Save files as UTF-8 and avoid mojibake/broken glyphs (`�`, `ↁE`, garbled sequences).
+- Keep canonical terminology stable across documents (for example: `bukken`, `sagyo`, `customer employee`).
+
+### 3.2 Markdown Structure Hygiene
+
+- Keep each heading on its own line; do not concatenate multiple headings/sections on one line.
+- Keep metadata blocks (`Information`, `Note`, `Behavior notes`) as structured bullet blocks, not single compressed lines.
+- Keep image, table, and separator (`---`) boundaries explicit to preserve parser/render stability.
+
+## 4. Item Numbering and Duplication Rules
+
+- Use one numbering mode only: `global across document`.
+- Number values must increase across all action tables in the document.
+- Avoid duplicate item descriptions for the same UI control across screens unless behavior differs.
+- If duplicate number is intentional (rare), annotate reason in `Note`.
+
+## 5. Screen Section Rules
+
+For each screen section:
+
+- Provide metadata:
+  - official screen name
+  - Screen ID
+  - design source URL (for example Figma)
+- Embed one representative image per screen.
+- Provide one action table.
+- Provide one API mapping table.
+- If a screen has dialogs, create explicit dialog sub-sections with their own tables and API mapping.
+
+## 6. API Traceability Rules
+
+- Every actionable UI event that changes state must map to a write API.
+- Every data-loading UI event must map to a read/search API.
+- If one endpoint serves multiple actions (initial load, search, refresh), state this explicitly.
+- If no API is called for an action, state `No API` and explain why.
+
+## 7. PlantUML Rules for Screen Flow
+
+- Use valid PlantUML syntax and renderability checks before handoff.
+- Use `\\n` for multi-line labels in nodes.
+- Keep diagram at navigation/action level (not low-level SQL or backend internals).
+- Ensure screen names in PlantUML match section names in layout spec.
+
+## 8. Data Source and Asset Rules
+
+- Prioritize source order:
+  1. Confirmed design source (for example Figma)
+  2. Confirmed requirement files (Excel/spec)
+  3. User-provided screenshots
+- Store images in repository-relative paths.
+- Do not keep temporary local absolute paths in markdown.
+
+## 9. Consistency with Other Specs
+
+- Align terms with:
+  - BA spec glossary
+  - API endpoints spec
+  - Database spec
+- If terminology differs across docs, raise an open question and add a temporary mapping note.
+- Keep endpoint paths in flow-action spec consistent with API endpoint spec.
+
+## 10. Open Questions and Uncertainty Handling
+
+- Capture unresolved items in `Open questions` table.
+- Do not invent UI behavior or API contracts when source is ambiguous.
+- Mark uncertain mappings as `Draft` and include impacted files/sections.
+
+## 11. Change Management
+
+- On each update:
+  - update impacted screen sections
+  - update API mapping tables
+  - update screen-to-API mapping summary
+  - append one row in document history
+- Never overwrite past history rows.
+
+## 12. Final Checklist Before Handoff
+
+- PlantUML renders successfully.
+- All mandatory sections exist.
+- All tables include `No`.
+- Numbering is global across the document (no resets).
+- No broken image links.
+- Screen/API mappings are consistent with `*_ENDPOINTS.md`.
+- Open questions are explicit and traceable.
+- For EN artifact: no leftover VI text outside allowed `Original Text` appendix blocks.
+- No mojibake/encoding corruption markers.
+- Headings/tables are structurally clean (no merged lines that break readability/traceability).

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/references/excel-image-export.md

@@ -0,0 +1,51 @@
+# Export anh tu Excel (sheet co hinh/shape) - tranh vo layout & loi anh trang
+
+## Khi nao can
+
+- Sheet `画面遷移` hoac `画面|...` chua hinh (picture/shape) thay vi text trong cell.
+- Can anh de embed vao markdown hoac overlay so.
+
+## Loi da gap & nguyen nhan
+
+1) `Chart.Export()` ra PNG trang (~1.3KB)
+- Nguyen nhan: Excel COM export chart/picture khong on dinh voi group/picture phuc tap.
+
+2) Sai duong dan thu muc anh khi SaveAs HTML
+- Excel tao folder anh theo quy uoc: `<basename>.files`
+- Vi du: `export.html` -> folder `export.files` (khong phai `export.html.files`).
+
+3) Excel COM crash / OLE error `0x800a01a8`
+- Nguyen nhan pho bien: goi `Quit()` nham instance Excel dang duoc attach boi COM (dac biet khi dung `Dispatch`).
+
+4) Marker 2 chu so bi mat digit (10 hien thi nhu 1)
+- Nguyen nhan: oval qua nho + wrap/align khong chuan.
+
+## Cach lam khuyen nghi (tu dong)
+
+Dung script trong repo, vi du:
+`Requirements/_generate_numbered_screen_images.py`
+
+Script nen dam bao:
+- Flatten group + SaveAs HTML de lay PNG that (tranh PNG trang).
+- Dung `DispatchEx` khi mo Excel rieng de overlay len PNG (tranh crash do Quit nham instance).
+- Tang size oval + tat WordWrap de hien thi du 2-3 chu so.
+- Su dung dung quy uoc `.files` folder khi export HTML.
+
+Chay (vi du, tai project root):
+```powershell
+python Requirements\_generate_numbered_screen_images.py
+```
+
+## Cach lam thu cong (fallback)
+
+1) Mo Excel -> chon vung UI can export (picture/group) -> Copy as Picture.
+2) Paste sang sheet trong hoac workbook moi.
+3) Save As -> "Web Page (*.htm; *.html)".
+4) Vao folder `<basename>.files` -> chon file `imageXXX.png` co kich thuoc phu hop nhat.
+5) Copy sang `docs/specs/assets/[feature_snake]/screens/` va dat ten theo convention.
+
+## Luu y khi script fail do ten Picture thay doi
+
+Neu script tham chieu theo `picture_name` (vd: `Picture 4`, `Picture 7`), khi Excel doi ten:
+- Mo Excel -> chon picture -> xem/doi ten trong Selection Pane, hoac
+- Cap nhat lai `picture_name` trong script.

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/references/figma-mcp.md

@@ -0,0 +1,54 @@
+# Figma MCP: lay layout/style/tokens + export anh
+
+## Parse URL Figma
+
+Mau URL:
+`https://www.figma.com/design/<fileKey>/<fileName>?node-id=<nodeId>&m=dev&t=...`
+
+- `fileKey` = segment sau `/design/`.
+- `nodeId`:
+  - query param `node-id=1-2695`
+  - chuyen sang format API: `1:2695` (thay `-` bang `:`).
+
+## Lay du lieu layout/style (uu tien)
+
+Dung MCP:
+- `mcp__figma__get_figma_data`
+  - Input: `fileKey`, `nodeId`
+  - Goi y: thu `depth=2` hoac `depth=3` (tang dan neu thieu thong tin).
+
+Khi tong hop vao `docs/specs/[FEATURE_KEY]_FIGMA_LAYOUT.md`, giu khung:
+- Design Structure: frame dimensions, components/instances, key layers, variants/properties.
+- Styling Data: color (Hex/RGB), typography (font/size/weight/line-height), shadow/opacity/border.
+- Layout Information: padding/gap/alignment, width/height, border radius.
+- Design Tokens: color/typography/spacing tokens neu co ten style (vd: `style_...`).
+
+## Rate-limit 429 / du lieu thieu
+
+Neu gap `429 Too Many Requests`:
+1) Giam `depth` va thu lai.
+2) Cho va retry (backoff 20s -> 40s -> 80s).
+3) Neu van fail: de trong cac muc khong lay duoc va ghi note ro ly do 429.
+
+Khong tu bịa mau/typography/token khi khong co du lieu.
+
+## Export anh man hinh
+
+Dung MCP:
+- `mcp__figma__download_figma_images`
+  - Input: `fileKey`, danh sach `nodes` (nodeId), `fileName` (png), `pngScale` (thuong 2).
+
+Luu y ve `localPath`:
+- Mot so moi truong chan duong dan tuyet doi.
+- Dung thu muc tuong doi trong repo (vd: `Requirements/_tmp/figma_downloads`) roi copy anh ve:
+  - `docs/specs/assets/[feature_snake]/screens/`
+
+## Quy uoc dat ten file anh
+
+Khuyen nghi dat ten on dinh de embed lau dai, vi du:
+- `screen_3_1_main.png`
+- `screen_3_2_search.png`
+- `screen_3_3_dialog.png`
+- `screen_3_3_dialog_numbered.png`
+
+Neu dung anh tu Excel thay the, van giu cung naming de tranh sua nhieu link trong markdown.

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/references/numbering-rules.md

@@ -0,0 +1,76 @@
+# Quy tắc đánh số UI item (Flow Action Spec)
+
+## Mục tiêu
+
+- Gắn số lên ảnh màn hình để người đọc map nhanh sang bảng action.
+- Đánh số **toàn cục**, tăng dần theo thứ tự màn hình trong flow.
+- **Không trùng số** giữa các item mới.
+- **Không lặp mô tả** item đã xuất hiện ở màn hình trước.
+
+## Quy ước “item đã xuất hiện”
+
+Xem item là “đã xuất hiện” nếu:
+- Cùng ý nghĩa chức năng và cùng vị trí/khu vực UI (dù ở chế độ view khác).
+- Đã được đánh số trong một màn hình trước đó.
+
+Hệ quả:
+- Màn hình sau **không thêm dòng mới** vào bảng action cho item này.
+- Nếu cần người đọc định vị, vẫn có thể giữ số trên ảnh (để đối chiếu), nhưng ghi chú trong section: “Đã mô tả ở màn X (No Y)”.
+
+## Cách làm chuẩn (không đoán khi thiếu dữ liệu)
+
+1) Xác định thứ tự màn hình trong flow (mặc định theo danh sách Figma + luồng `画面遷移`).
+2) Tạo “sổ tay đánh số” (mapping) dạng:
+   - `key` (tên/nhãn JP + loại control + khu vực)
+   - `value` (số No)
+3) Với từng màn hình:
+   - Liệt kê item tương tác cần mô tả (button/link/selectbox/checkbox…).
+   - Nếu item mới: cấp số tiếp theo và thêm vào mapping.
+   - Nếu item cũ: không cấp số mới, không lặp mô tả.
+4) Nếu **chưa xác định được vị trí đặt số trên ảnh**:
+   - Yêu cầu user cung cấp ảnh có đánh dấu hoặc chỉ rõ vị trí (tỷ lệ/tọa độ/ô Excel).
+   - Không tự suy đoán vị trí.
+
+## Nguồn dữ liệu tham khảo
+
+- Excel: sheet `画面|作業員割付` (bảng mô tả + cột BK thường chứa ký hiệu số tròn ㉕/㉖…)
+  - Ví dụ:
+    - `BK205`: `㉕リスト表示切替ボタン`
+    - `BK245`: `㉖マグネット表示切替ボタン`
+- Ảnh/screenshot đã được user đánh số (nguồn xác thực tốt nhất).
+- Ảnh export từ Figma/Excel để overlay số.
+
+## Case lỗi đã gặp & cách tránh
+
+### 1) Trùng số “1” trong màn Search / Edit
+
+Nguyên nhân thường gặp:
+- Overlay tool chỉ đọc được “1” khi marker là 2 chữ số (10,11,12…).
+
+Cách tránh:
+- Khi tạo marker (oval) cho 2+ chữ số, tăng kích thước tối thiểu (>= 32px) và tắt WordWrap.
+- Nếu lấy marker từ Excel, đảm bảo marker trong Excel hiển thị đúng 2 chữ số trước khi export.
+
+### 2) Excel spec bị “duplicate numbering” (ví dụ ㉑ xuất hiện 2 lần)
+
+Nguyên nhân:
+- Dữ liệu Excel gốc bị trùng ký hiệu số.
+
+Cách xử lý:
+- Ưu tiên theo logic UI + screenshot user xác nhận.
+- Renumber phần bị duplicate theo số tiếp theo (vd: 21 bị trùng → “đóng/xoá/search” thành 22/23/24 theo thứ tự thao tác).
+- Ghi chú rõ “Excel có duplicate; đã chuẩn hoá lại theo sequence toàn cục”.
+
+### 3) Item đã mô tả ở màn trước vẫn bị lặp trong bảng màn sau
+
+Cách tránh:
+- Trước khi thêm dòng vào bảng, đối chiếu mapping toàn cục.
+- Nếu cần nhắc lại, chỉ thêm bullet note “đã mô tả ở …”, không thêm dòng mới trong bảng.
+
+## Ví dụ theo dự án tham chiếu
+
+- Màn 3.1 (Bukken View): đã đánh số 1–9.
+- Màn 3.2 (Search): tiếp tục 10–24.
+- Màn 3.3 (Bukken Magnet): chỉ đánh số 25 cho nút chuyển List.
+- Màn 3.4 (Bukken List): chỉ đánh số 26 cho nút chuyển Magnet.
+- Màn 3.7 (Worker Magnet): chỉ đánh số các item mới theo yêu cầu (vd: selectbox 物件名, nút 検索, checkbox 複数日登録モード).

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/scripts/renumber_flow_action_spec_global.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+
+TABLE_ROW_RE = re.compile(r"^\|.*\|\s*$")
+TABLE_SEP_RE = re.compile(r"^\|\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|\s*$")
+
+
+def _split_table_row(line: str) -> list[str]:
+    return [p.strip() for p in line.strip().strip("|").split("|")]
+
+
+def _read_text(path: Path) -> tuple[str, str]:
+    for enc in ("utf-8-sig", "utf-8", "cp1252"):
+        try:
+            return path.read_text(encoding=enc), enc
+        except UnicodeDecodeError:
+            continue
+    return path.read_text(errors="replace"), "utf-8"
+
+
+def _make_row(cells: list[str]) -> str:
+    return "| " + " | ".join(cells) + " |"
+
+
+def renumber_action_tables(md_text: str) -> tuple[str, int, int]:
+    lines = md_text.splitlines()
+    out = lines[:]
+
+    expected_no = 1
+    touched = 0
+    rows = 0
+
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if i + 1 < len(lines) and TABLE_ROW_RE.match(line) and TABLE_ROW_RE.match(lines[i + 1]):
+            header = _split_table_row(line)
+            if not TABLE_SEP_RE.match(lines[i + 1]):
+                i += 1
+                continue
+
+            lowered = [h.lower() for h in header]
+            if "action" not in lowered or "description" not in lowered:
+                i += 1
+                continue
+            if "no" in lowered:
+                no_index = lowered.index("no")
+            elif "no." in lowered:
+                no_index = lowered.index("no.")
+            else:
+                i += 1
+                continue
+
+            j = i + 2
+            while j < len(lines) and TABLE_ROW_RE.match(lines[j]):
+                row = _split_table_row(lines[j])
+                if len(row) <= no_index:
+                    j += 1
+                    continue
+
+                try:
+                    current_no = int(row[no_index])
+                except ValueError:
+                    j += 1
+                    continue
+
+                rows += 1
+                if current_no != expected_no:
+                    row[no_index] = str(expected_no)
+                    out[j] = _make_row(row)
+                    touched += 1
+                expected_no += 1
+                j += 1
+
+            i = j
+            continue
+
+        i += 1
+
+    return "\n".join(out) + "\n", rows, touched
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Renumber action table `No` fields globally in *_FLOW_ACTION_SPEC.md"
+    )
+    parser.add_argument("--spec", required=True, help="Path to *_FLOW_ACTION_SPEC.md")
+    parser.add_argument(
+        "--write",
+        action="store_true",
+        help="Write changes to file. Without this flag, runs in dry-run mode.",
+    )
+    args = parser.parse_args()
+
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
+        sys.stderr.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
+    except Exception:
+        pass
+
+    spec_path = Path(args.spec)
+    if not spec_path.exists():
+        print(f"[ERROR] Not found: {spec_path}", file=sys.stderr)
+        return 2
+
+    text, enc = _read_text(spec_path)
+    new_text, rows, touched = renumber_action_tables(text)
+
+    print(f"Checked: {spec_path}")
+    print(f"- Numbered action rows: {rows}")
+    print(f"- Rows changed: {touched}")
+    print(f"- Mode: {'write' if args.write else 'dry-run'}")
+
+    if touched == 0:
+        print("[OK] Already globally numbered.")
+        return 0
+
+    if not args.write:
+        print("[INFO] Re-run with --write to apply changes.")
+        return 1
+
+    if enc not in ("utf-8", "utf-8-sig"):
+        enc = "utf-8"
+    spec_path.write_text(new_text, encoding=enc)
+    print("[OK] Updated file with global numbering.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+