sdtk-kit 0.3.8 → 0.3.9

package/assets/toolkit/toolkit/skills/sdtk-design-layout/SKILL.md

@@ -8,6 +8,8 @@ description: Generate UI screen layout documentation for a feature, including Pl
 ## Critical Constraints
 - I do not skip screen IDs or item numbering alignment with the wireframe.
 - I do not hide render limitations; I record when screen preview rendering is unavailable.
+- I do not leave rendered wireframes without visible local item markers that map back to the `Items` table.
+- I do not pretend wireframe markers are the same thing as `FLOW_ACTION_SPEC` global action-table numbers.
 
 ## Output
 - `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md`
@@ -15,13 +17,23 @@ description: Generate UI screen layout documentation for a feature, including Pl
 ## Process
 1. Read BA spec (screens + fields) and API list.
 2. For each screen, include:
-   - PlantUML `@startsalt` wireframe first
+   - PlantUML `@startsalt` wireframe first, with visible screen-local markers embedded directly in the SALT labels
    - API list table
-   - Item table with numbering that matches the wireframe
-3. Keep screen IDs consistent (A-*, B-*, C-*).
-4. After writing `DESIGN_LAYOUT`, attempt to render screen preview images by default:
+   - Item table whose `No` values exactly match the local marker sequence used in the wireframe for that screen
+3. Use this wireframe-marker convention so the rendered SVG can be cross-referenced visually:
+   - markers are screen-local visual references and reset per screen
+   - prefer Unicode circled-number markers in generated docs; avoid parenthetical `(N)` markers because they blend into UI text and can conflict with SALT parsing
+   - text label or input prompt: prefix the visible label with the local marker
+   - button: place the local marker inside the visible button label
+   - table header: prefix the header text with the local marker
+   - standalone control, pagination, toggle, or status chip: prefix the visible label with the local marker
+   - do not rely on prose, comments, or a separate legend; the marker must be visible inside the rendered wireframe itself
+   - the local marker does not need to equal the `FLOW_ACTION_SPEC` global `No`; `screen-design-spec` publishes the mapping table
+4. Keep screen IDs consistent (A-*, B-*, C-*).
+5. After writing `DESIGN_LAYOUT`, attempt to render screen preview images by default:
    - Run `render_design_layout_images.py` to extract `@startsalt` blocks and render `.svg` files.
    - Output path: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
+   - The renderer warns if a screen wireframe has no visible local markers or still uses legacy `(N)` markers.
    - If PlantUML is unavailable, rendering is skipped with a warning and the render-skipped note is used in `FLOW_ACTION_SPEC`. The layout doc remains valid.
 
 ## Screen Image Renderer
@@ -38,4 +50,3 @@ description: Generate UI screen layout documentation for a feature, including Pl
 
 ## Template
 - Use `toolkit/templates/docs/design/DESIGN_LAYOUT_TEMPLATE.md` as starting structure.
-

package/assets/toolkit/toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py

@@ -21,6 +21,10 @@ from pathlib import Path
 from typing import List, Optional, Tuple
 
 
+CIRCLED_ITEM_MARKER_RE = re.compile(r"[\u2460-\u2473\u3251-\u325F\u32B1-\u32BF]")
+LEGACY_ITEM_MARKER_RE = re.compile(r"\(\d+\)")
+
+
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
         description="Render screen images from DESIGN_LAYOUT PlantUML SALT blocks."
@@ -100,12 +104,20 @@ def extract_screens(text: str) -> List[Tuple[str, str]]:
     return screens
 
 
+def count_visible_item_markers(salt_block: str) -> int:
+    return len(CIRCLED_ITEM_MARKER_RE.findall(salt_block))
+
+
+def count_legacy_item_markers(salt_block: str) -> int:
+    return len(LEGACY_ITEM_MARKER_RE.findall(salt_block))
+
+
 def render_svg(
     plantuml_jar: Path, puml_path: Path, output_dir: Path
 ) -> Optional[str]:
     """Render a single .puml to .svg. Returns error string or None on success."""
     proc = subprocess.run(
-        ["java", "-jar", str(plantuml_jar), "-tsvg", str(puml_path)],
+        ["java", "-Dfile.encoding=UTF-8", "-jar", str(plantuml_jar), "-charset", "UTF-8", "-tsvg", str(puml_path)],
         stdout=subprocess.PIPE,
         stderr=subprocess.STDOUT,
         text=True,
@@ -166,6 +178,19 @@ def main() -> int:
 
     print(f"[OK] Found {len(screens)} screen(s) with SALT wireframes.")
 
+    numbering_warnings: List[str] = []
+    for screen_id, salt_block in screens:
+        marker_count = count_visible_item_markers(salt_block)
+        legacy_marker_count = count_legacy_item_markers(salt_block)
+        if legacy_marker_count > 0:
+            numbering_warnings.append(
+                f"{screen_id}: legacy `(N)` markers detected; prefer circled-number markers to avoid SALT ambiguity."
+            )
+        elif marker_count == 0:
+            numbering_warnings.append(
+                f"{screen_id}: no visible wireframe item markers found."
+            )
+
     # Write .puml files
     puml_files: List[Path] = []
     for screen_id, salt_block in screens:
@@ -176,6 +201,10 @@ def main() -> int:
 
     if args.skip_render:
         print(f"[OK] Wrote {len(puml_files)} .puml file(s). Render skipped (--skip-render).")
+        if numbering_warnings:
+            print("[WARN] Wireframe numbering issues:")
+            for item in numbering_warnings:
+                print(f"  - {item}")
         return 0
 
     # Find PlantUML
@@ -201,6 +230,10 @@ def main() -> int:
         print("[WARN] Render issues:")
         for item in errors:
             print(f"  - {item}")
+    if numbering_warnings:
+        print("[WARN] Wireframe numbering issues:")
+        for item in numbering_warnings:
+            print(f"  - {item}")
 
     return 0
 

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

@@ -8,6 +8,10 @@ description: Create/update screen flow-action specifications from requirement so
 ## Critical Constraints
 - I do not finalize UI-scope screens without a valid design source type and reference.
 - I do not leave broken image paths or incomplete API mappings in the flow-action spec.
+- I use new-style PlantUML activity diagram syntax only for the screen flow diagram.
+- I do not mix legacy and new-style PlantUML activity syntax in the screen flow diagram.
+- Do not mix legacy activity syntax such as `(*)`, `-->`, or `[edge label]` with new-style activity actions like `:Activity;`.
+- I keep action-table numbering global across the document even when wireframe markers reset per screen.
 
 ## Outputs
 - `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`
@@ -35,6 +39,7 @@ description: Create/update screen flow-action specifications from requirement so
 5. For each screen/dialog:
    - Add metadata (screen ID, Design Source Type, Design Source Reference)
    - Add screen image reference (from Figma, screenshot, or rendered `.svg` from generated layout)
+   - For generated-draft wireframes, add a wireframe-marker mapping table from the screen-local wireframe markers to the global action-table `No`
    - Add UI item/action table with `No` column
    - Add API mapping table (trigger -> API -> data usage)
 6. Build/update `System processing flow` from use-case and process sources.
@@ -43,15 +48,21 @@ description: Create/update screen flow-action specifications from requirement so
 9. Validate:
    - global numbering consistency (no screen-level reset)
    - no broken image paths (for `generated-draft` screens, verify `.svg` exists or use render-skipped note)
-   - PlantUML renderability
+   - PlantUML renderability and new-style activity syntax consistency (no `(*)`, `-->`, or `[edge label]` mixing)
    - 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
    - every UI-scope screen declares a Design Source Type (`source-backed` or `generated-draft`)
+   - every generated-draft screen with an embedded wireframe image includes a wireframe-marker mapping table to the global action-table `No`
 10. For `generated-draft` screens, set `Screen image:` to the rendered `.svg` path if the file exists:
-    - Expected path: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
+    - Expected path (filesystem): `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
+    - Markdown image path (file-relative): `assets/<feature_snake>/screens/<screen_id>.svg`
     - If the `.svg` does not exist (render unavailable), replace the image reference with: `> Screen image not rendered in this environment. See Design Source Reference for layout.`
-11. Update document history and handoff to ARCH/DEV.
+11. For generated-draft screens, treat wireframe markers as screen-local visual references:
+    - the local marker sequence may reset per screen
+    - do not renumber the wireframe to fake equality with the global action-table `No`
+    - publish the mapping table directly under the screen image so reviewers can cross-reference local markers to global action-table numbers
+12. Update document history and handoff to ARCH/DEV.
 
 ## Rule References
 - Core rules: `./references/FLOW_ACTION_SPEC_CREATION_RULES.md`
@@ -63,6 +74,8 @@ description: Create/update screen flow-action specifications from requirement so
 - `scripts/validate_flow_action_spec_numbering.py`
   - Checks duplicate/resetted numbering in action tables.
   - Checks encoding/markdown hygiene.
+  - Checks screen-image markdown path convention.
+  - Checks mixed legacy/new-style PlantUML activity syntax in screen-flow diagrams.
   - 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`
@@ -70,4 +83,4 @@ description: Create/update screen flow-action specifications from requirement so
   - 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`
+    - `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

@@ -94,6 +94,7 @@ If a section is not in scope, keep the section and mark explicitly as `N/A` with
 
 - Use one numbering mode only: `global across document`.
 - Number values must increase across all action tables in the document.
+- DESIGN_LAYOUT wireframe markers are a separate screen-local visual system. They may reset per screen and do not need to numerically equal the global action-table `No`.
 - Avoid duplicate item descriptions for the same UI control across screens unless behavior differs.
 - If duplicate number is intentional (rare), annotate reason in `Note`.
 
@@ -127,6 +128,19 @@ Rules:
 - The flow-action spec and the design-layout doc must remain separate documents.
 - When Figma becomes available later, update the source mode from `generated-draft` to `source-backed`.
 
+## 5.2 Wireframe Marker Mapping for Generated-Draft Screens
+
+For generated-draft screens with rendered design-layout images:
+
+- Treat wireframe markers as screen-local visual references only.
+- Keep action-table `No` global across the document per section 4.
+- Add a wireframe marker mapping table directly under the screen image.
+- Use this stable header:
+  - `No | Wireframe Marker | Action Table No | Item Name | Notes`
+- Map only the items visibly present on the wireframe image.
+- If an action-table row is not visible on the wireframe, state `Not shown on wireframe` in `Notes` instead of inventing a marker.
+- If the wireframe label and the action-table label differ slightly, keep the action-table item name and explain the label difference in `Notes`.
+
 ## 6. API Traceability Rules
 
 - Every actionable UI event that changes state must map to a write API.
@@ -136,8 +150,11 @@ Rules:
 
 ## 7. PlantUML Rules for Screen Flow
 
-- Use valid PlantUML syntax and renderability checks before handoff.
-- Use `\\n` for multi-line labels in nodes.
+- Use new-style PlantUML activity diagram syntax only for screen-flow diagrams.
+- Allowed activity constructs include: `start`, `stop`, `partition "..." {}`, `:Activity;`, `->`, `if/then/else/endif`, `fork`, `fork again`, `end fork`, and `note right/left`.
+- Do not mix legacy activity syntax such as `(*)`, `-->`, or `[edge label]` with new-style activity actions like `:Activity;`.
+- Validate renderability before handoff. If a renderer is unavailable in the current environment, at minimum keep the block internally consistent with new-style activity syntax only.
+- Use `\\n` for multi-line labels in activity nodes and notes.
 - Keep diagram at navigation/action level (not low-level SQL or backend internals).
 - Ensure screen names in PlantUML match section names in layout spec.
 
@@ -147,7 +164,8 @@ Rules:
   1. Confirmed design source (for example Figma)
   2. Confirmed requirement files (Excel/spec)
   3. User-provided screenshots
-- Store images in repository-relative paths.
+- Store images in repository-relative filesystem paths.
+- Reference images in markdown using file-relative paths from the spec file's directory.
 - Do not keep temporary local absolute paths in markdown.
 
 ### 8.1 Rendered Screen Images for Generated-Draft Screens
@@ -155,8 +173,10 @@ Rules:
 When `Design Source Type` is `generated-draft`:
 - Screen preview images may be rendered from `DESIGN_LAYOUT_[FEATURE_KEY].md` PlantUML SALT wireframes.
 - Renderer: `toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py`
-- Expected output path: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
-- If the rendered `.svg` file exists, use it as the `Screen image:` reference.
+- Expected output path (filesystem): `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
+- Markdown image path (file-relative from `docs/specs/*_FLOW_ACTION_SPEC.md`): `assets/<feature_snake>/screens/<screen_id>.svg`
+- DESIGN_LAYOUT markers inside the image are screen-local visual references and may reset per screen; use the wireframe mapping table to bridge them to the global action-table `No`.
+- If the rendered `.svg` file exists, use the file-relative markdown path in the `Screen image:` reference.
 - If rendering is unavailable or the `.svg` does not exist, replace the image line with:
   `> Screen image not rendered in this environment. See Design Source Reference for layout.`
 - Do not leave a broken image reference pointing to a non-existent file.

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

@@ -1,76 +1,28 @@
-# Quy tắc đánh số UI item (Flow Action Spec)
+# UI Numbering Policy
 
-## Mục tiêu
+## Scope
 
-- 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.
+- `FLOW_ACTION_SPEC` action tables use one numbering mode only: global across the full document.
+- `DESIGN_LAYOUT` wireframe markers are screen-local visual references and may reset per screen.
+- Do not force wireframe marker values to numerically equal the global action-table `No`.
 
-## Quy ước “item đã xuất hiện”
+## DESIGN_LAYOUT Rules
 
-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 đó.
+- Every visible wireframe control should have a visible local marker.
+- Prefer Unicode circled-number markers in generated design docs.
+- Avoid parenthetical `(N)` markers because they blend into UI text and can conflict with SALT parser behavior.
+- Local wireframe markers only cover items visibly present on that screen.
 
-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)”.
+## FLOW_ACTION_SPEC Rules
 
-## Cách làm chuẩn (không đoán khi thiếu dữ liệu)
+- Keep action-table `No` values global across the document.
+- For each generated-draft screen with an embedded wireframe image, add a wireframe marker mapping table:
+  - `No | Wireframe Marker | Action Table No | Item Name | Notes`
+- The mapping table bridges screen-local wireframe markers to global action-table numbers.
+- If an action-table item is not visible on the wireframe, note that explicitly instead of inventing a marker.
 
-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í.
+## Non-1:1 Mapping Cases
 
-## 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 複数日登録モード).
+- If the wireframe label and the action-table label differ slightly, use the action-table item name in the mapping table and explain the label difference in `Notes`.
+- If multiple action-table rows map to one visual region, spell that out in `Notes`.
+- If a dialog, hidden state, or validation item is not shown on the wireframe, mark it as `Not shown on wireframe`.

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

@@ -10,6 +10,7 @@ from pathlib import Path
 TABLE_ROW_RE = re.compile(r"^\|.*\|\s*$")
 TABLE_SEP_RE = re.compile(r"^\|\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|\s*$")
 HEADING_RE = re.compile(r"^(#{1,6})\s+(.*\S)\s*$")
+SCREEN_SECTION_HEADING_RE = re.compile(r"^###\s+(.*\S)\s*$", re.MULTILINE)
 VI_DIACRITIC_RE = re.compile(r"[À-ỹ]")
 VI_PHRASE_RE = re.compile(
     r"\b("
@@ -19,6 +20,15 @@ VI_PHRASE_RE = re.compile(
     re.IGNORECASE,
 )
 INLINE_HEADING_RE = re.compile(r".+\s#{2,}\s+\S")
+IMAGE_LINK_RE = re.compile(r"!\[[^\]]*\]\(([^)]+)\)")
+PLANTUML_FENCE_START_RE = re.compile(r"^\s*```plantuml\s*$", re.IGNORECASE)
+NEW_STYLE_ACTIVITY_LINE_RE = re.compile(
+    r"^\s*(start|stop|partition\s+\"|if\s*\(|fork(?:\s+again)?\b|end\s+fork\b|note\s+(?:right|left|top|bottom)\b|:[^;\n]+;)",
+    re.IGNORECASE,
+)
+LEGACY_ACTIVITY_START_RE = re.compile(r"\(\*\)")
+LEGACY_EDGE_LABEL_RE = re.compile(r"-->\s*\[")
+MIXED_ACTIVITY_ARROW_RE = re.compile(r":[^;\n]+;\s*-->")
 
 
 @dataclass(frozen=True)
@@ -82,6 +92,134 @@ def collect_hygiene_issues(md_text: str, *, en_check: bool) -> dict[str, list[tu
     return issues
 
 
+def _is_root_relative_docs_href(href: str) -> bool:
+    normalized = href.strip().replace("\\", "/").lower()
+    if not normalized:
+        return False
+    if re.match(r"^[a-z][a-z0-9+.-]*://", normalized):
+        return False
+    if normalized.startswith(("mailto:", "tel:", "data:", "#")):
+        return False
+    return normalized.startswith(("docs/", "./docs/", "/docs/"))
+
+
+def collect_screen_image_path_issues(md_text: str) -> list[tuple[int, str]]:
+    issues: list[tuple[int, str]] = []
+    lines = md_text.splitlines()
+    in_code_block = False
+    expecting_image_line = False
+
+    for idx, line in enumerate(lines, start=1):
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            in_code_block = not in_code_block
+            expecting_image_line = False
+            continue
+        if in_code_block:
+            continue
+        if not stripped:
+            continue
+
+        if stripped.lower().startswith("screen image:"):
+            expecting_image_line = stripped.lower() == "screen image:"
+            hrefs = IMAGE_LINK_RE.findall(stripped)
+        elif expecting_image_line and stripped.startswith("!["):
+            expecting_image_line = False
+            hrefs = IMAGE_LINK_RE.findall(stripped)
+        else:
+            hrefs = []
+            if not stripped.startswith("<!--"):
+                expecting_image_line = False
+
+        for href in hrefs:
+            if _is_root_relative_docs_href(href):
+                issues.append((idx, href))
+
+    return issues
+
+
+def collect_plantuml_activity_syntax_issues(md_text: str) -> list[tuple[int, str]]:
+    issues: list[tuple[int, str]] = []
+    lines = md_text.splitlines()
+    in_plantuml_block = False
+    block_start_line = 0
+    block_lines: list[str] = []
+
+    def flush_block() -> None:
+        nonlocal issues, block_lines, block_start_line
+        if not block_lines:
+            return
+        has_new_style = any(NEW_STYLE_ACTIVITY_LINE_RE.search(line) for line in block_lines)
+        if not has_new_style:
+            block_lines = []
+            block_start_line = 0
+            return
+
+        for offset, line in enumerate(block_lines, start=0):
+            line_no = block_start_line + offset
+            if LEGACY_ACTIVITY_START_RE.search(line):
+                issues.append(
+                    (line_no, "Legacy activity start marker `(*)` is not allowed in new-style activity diagrams.")
+                )
+            if MIXED_ACTIVITY_ARROW_RE.search(line):
+                issues.append(
+                    (line_no, "Do not append legacy `-->` transitions after a new-style `:Activity;` action line.")
+                )
+            elif LEGACY_EDGE_LABEL_RE.search(line):
+                issues.append(
+                    (line_no, "Legacy edge labels like `--> [label]` are not allowed in new-style activity diagrams.")
+                )
+
+        block_lines = []
+        block_start_line = 0
+
+    for idx, line in enumerate(lines, start=1):
+        if not in_plantuml_block and PLANTUML_FENCE_START_RE.match(line):
+            in_plantuml_block = True
+            block_start_line = idx + 1
+            block_lines = []
+            continue
+
+        if in_plantuml_block and line.strip().startswith("```"):
+            flush_block()
+            in_plantuml_block = False
+            continue
+
+        if in_plantuml_block:
+            block_lines.append(line)
+
+    if in_plantuml_block:
+        flush_block()
+
+    return issues
+
+
+def collect_wireframe_mapping_issues(md_text: str) -> list[tuple[int, str]]:
+    issues: list[tuple[int, str]] = []
+    sections = list(SCREEN_SECTION_HEADING_RE.finditer(md_text))
+    for idx, match in enumerate(sections):
+        start = match.start()
+        end = sections[idx + 1].start() if idx + 1 < len(sections) else len(md_text)
+        section_text = md_text[start:end]
+
+        if "Design Source Type: generated-draft" not in section_text:
+            continue
+        if "> Screen image not rendered in this environment." in section_text:
+            continue
+        if "Screen image:" not in section_text or "![" not in section_text:
+            continue
+        if "#### Wireframe Marker Mapping" in section_text:
+            continue
+
+        line_no = md_text.count("\n", 0, start) + 1
+        section_name = match.group(1).strip()
+        issues.append(
+            (line_no, f"{section_name}: missing `Wireframe Marker Mapping` table for generated-draft screen.")
+        )
+
+    return issues
+
+
 def parse_action_tables(md_text: str) -> list[Occurrence]:
     occurrences: list[Occurrence] = []
     current_section = ""
@@ -172,9 +310,6 @@ def main() -> int:
 
     text = _read_text(spec_path)
     occ = parse_action_tables(text)
-    if not occ:
-        print("[WARN] No action tables detected (| No | Action | Description | ... |).")
-        return 0
 
     by_number: dict[int, list[Occurrence]] = {}
     for o in occ:
@@ -191,16 +326,28 @@ def main() -> int:
 
     has_issues = bool(duplicates or decreases)
     hygiene = collect_hygiene_issues(text, en_check=args.en_check)
+    image_path_issues = collect_screen_image_path_issues(text)
+    plantuml_activity_issues = collect_plantuml_activity_syntax_issues(text)
+    wireframe_mapping_issues = collect_wireframe_mapping_issues(text)
     if hygiene["encoding"] or hygiene["inline_heading"]:
         has_issues = True
     if args.en_check and (hygiene["vi_diacritic"] or hygiene["vi_phrase"]):
         has_issues = True
+    if image_path_issues:
+        has_issues = True
+    if plantuml_activity_issues:
+        has_issues = True
+    if wireframe_mapping_issues:
+        has_issues = True
 
     print(f"Checked: {spec_path}")
     print(f"- Total numbered rows: {len(occ)}")
     print(f"- Unique numbers: {len(by_number)}")
     print(f"- EN hygiene check enabled: {args.en_check}")
 
+    if not occ:
+        print("[WARN] No action tables detected (| No | Action | Description | ... |).")
+
     if duplicates:
         print("\n[FAIL] Duplicate numbers found:")
         for n in sorted(duplicates.keys()):
@@ -233,6 +380,21 @@ def main() -> int:
         for line_no, line in hygiene["vi_phrase"][:20]:
             print(f"- line {line_no}: {line.strip()}")
 
+    if image_path_issues:
+        print("\n[FAIL] Screen image markdown paths must be file-relative, not docs-root-relative:")
+        for line_no, href in image_path_issues[:20]:
+            print(f"- line {line_no}: {href}")
+
+    if plantuml_activity_issues:
+        print("\n[FAIL] Mixed or legacy PlantUML activity syntax detected in a new-style screen-flow block:")
+        for line_no, message in plantuml_activity_issues[:20]:
+            print(f"- line {line_no}: {message}")
+
+    if wireframe_mapping_issues:
+        print("\n[FAIL] Missing wireframe-marker mapping tables for generated-draft screens:")
+        for line_no, message in wireframe_mapping_issues[:20]:
+            print(f"- line {line_no}: {message}")
+
     if not has_issues:
         print("\n[OK] Numbering and text hygiene checks passed.")
         return 0
@@ -240,6 +402,9 @@ def main() -> int:
     print("\nHint: Use global numbering across the full document.")
     print("- Do not repeat No values in any action table.")
     print("- Do not reset numbering per screen/dialog.")
+    print("- Use file-relative screen image paths such as assets/<feature>/screens/<screen>.svg.")
+    print("- Use new-style PlantUML activity syntax only for screen-flow diagrams.")
+    print("- Add a `Wireframe Marker Mapping` table when a generated-draft screen embeds a wireframe image.")
     print("- Keep EN artifacts free of Vietnamese leftovers and encoding corruption.")
     print("- Keep headings/sections on separate lines (avoid merged markdown blocks).")
     return 1

package/assets/toolkit/toolkit/skills-claude/api-design-spec/SKILL.md

@@ -1,18 +1,22 @@
 ---
 name: api-design-spec
-description: Generate detailed API design markdown from OpenAPI YAML and API flow list using Excel-style structure rules. Use when you need field-level request/response tables + per-endpoint process flow images for implementation/review handoff.
+description: Generate detailed API design markdown from OpenAPI YAML and API flow list. Use when you need field-level request/response tables plus one visible process-flow diagram per API.
 ---
 
 ## Required Inputs (read before proceeding)
 Read the following artifacts for the current feature:
-1. `docs/api/[FeaturePascal]_API.yaml` — API contract
-2. `docs/api/[feature_snake]_api_flow_list.txt` — flow list
+1. `docs/api/[FeaturePascal]_API.yaml` - API contract
+2. `docs/api/[feature_snake]_api_flow_list.txt` - flow list
 
 ## Input
 $ARGUMENTS
 
 # SDTK API Design Detail Spec
 
+## Critical Constraints
+- I do not drift from the source YAML or flow list.
+- I do not leave broken flow image embeds in the generated markdown.
+
 ## Outputs
 - `docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md`
 - Supporting generated assets:
@@ -40,15 +44,15 @@ $ARGUMENTS
 ## Generation Procedure
 1. Resolve input files (`yaml`, `flow_list`, `output`).
 2. Parse YAML endpoints (method, path, request schema, success/error schema).
-3. Parse flow blocks from flow list (`@startuml ... @enduml`) and map by `METHOD + path`.
+3. Parse flow blocks from flow list and map them by normalized `METHOD + path`.
 4. Generate detailed markdown sections per API:
    - Flow summary / notes / login bullets from YAML `description`
    - Process flow source block (`text` fenced block)
    - Embedded flowchart image
    - Path parameter table
-   - Request table (hierarchy levels + type + format + required)
+   - Request table
    - Success response table
-   - Error response table (explicit schema if defined, otherwise shared envelope + inferred business statuses from flow)
+   - Error response table
 5. Generate/update `.puml` per API under `docs/api/flows`.
 6. Render `.svg` images under `docs/api/images`.
 7. Validate:
@@ -58,17 +62,27 @@ $ARGUMENTS
    - markdown tables keep `No` sequential numbering
 
 ## Script
-- `scripts/generate_api_design_detail.py`
+- `.claude/skills/api-design-spec/scripts/generate_api_design_detail.py`
 
 ### Typical command
 ```bash
-python scripts/generate_api_design_detail.py \
+python ".claude/skills/api-design-spec/scripts/generate_api_design_detail.py" \
   --feature-key SCHEDULE_WHITEBOARD \
   --yaml "docs/api/ScheduleWhiteboard_API.yaml" \
   --flow-list "docs/api/schedule_whiteboard_api_flow_list.txt" \
   --output "docs/api/SCHEDULE_WHITEBOARD_API_DESIGN_DETAIL.md"
 ```
 
+### Optional subset generation
+```bash
+python ".claude/skills/api-design-spec/scripts/generate_api_design_detail.py" \
+  --feature-key SCHEDULE_WHITEBOARD \
+  --yaml "docs/api/ScheduleWhiteboard_API.yaml" \
+  --flow-list "docs/api/schedule_whiteboard_api_flow_list.txt" \
+  --output "docs/api/SCHEDULE_WHITEBOARD_API_DESIGN_DETAIL.md" \
+  --include "POST /api/whiteboard/assignment/{company_uuid}"
+```
+
 ## Orchestrator Integration (Hybrid)
 - `apiDesignDetailMode` in `sdtk.config.json` controls orchestration behavior:
   - `auto` (default): generate API design detail when ARCH has API scope and YAML/flow sources are available.