sdtk-kit 0.3.7 → 0.3.9

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-dev/SKILL.md

@@ -5,6 +5,10 @@ description: Developer workflow for SDTK. Use when you need to implement a featu
 
 # SDTK DEV (Implementation + Code Review)
 
+## Critical Constraints
+- I do not start implementation before the current `FEATURE_IMPL_PLAN` scope is approved.
+- I do not claim implementation is complete without fresh verification evidence.
+
 ## Outputs
 - `docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md`
 - Code + tests (follow repo conventions)

package/assets/toolkit/toolkit/skills/sdtk-dev-backend/SKILL.md

@@ -5,6 +5,10 @@ description: Generate/modify Python Django REST Framework backend code following
 
 # SDTK Backend (Toolkit conventions)
 
+## Critical Constraints
+- I do not generate backend code without approved API and data-contract sources.
+- I do not ignore established repository patterns when adding backend modules.
+
 ## Process
 1. Check whether this repository already has a backend reference module and follow its patterns.
 2. Follow module structure: `src/backend/<module>/{models,view,service,serializers,validation,enum,urls.py}`.

package/assets/toolkit/toolkit/skills/sdtk-dev-frontend/SKILL.md

@@ -5,6 +5,10 @@ description: Generate/modify React frontend code following the toolkit conventio
 
 # SDTK Frontend (Toolkit conventions)
 
+## Critical Constraints
+- I do not implement screens without current layout and flow-action sources.
+- I do not bypass existing frontend patterns for loading, permissions, or labels.
+
 ## Process
 1. Check whether this repository already has a frontend reference module and follow its patterns.
 2. Follow structure:

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

@@ -5,6 +5,10 @@ description: Orchestrate a full 6-phase SDLC multi-agent workflow (PM/BA/ARCH/DE
 
 # SDTK Orchestrator (multi-agent workflow)
 
+## Critical Constraints
+- I do not skip mandatory phases or hand off without current-phase evidence.
+- I do not treat planned commands as equivalent to completed work.
+
 ## Initialize
 - Ensure feature key + feature name exist (ask if missing).
 - Read `sdtk.config.json` (project stack + commands) if present.

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

@@ -5,6 +5,10 @@ description: Product Manager + meta-orchestrator workflow for SDTK. Use when you
 
 # SDTK PM (Entry Point + Planning)
 
+## Critical Constraints
+- I do not hand off PM work until `SHARED_PLANNING.md` and `QUALITY_CHECKLIST.md` reflect the current phase.
+- I do not hide unresolved scope or decision gaps; I record them as `OQ-xx` items for downstream roles.
+
 ## 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`

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

@@ -5,6 +5,10 @@ description: QA workflow for SDTK. Use when you need to validate an implemented
 
 # SDTK QA (Testing + Release Decision)
 
+## Critical Constraints
+- I do not start QA handoff or release decision work until both DEV review gates PASS.
+- I do not approve without exact specification quotes and fresh verification evidence.
+
 ## Output
 - `docs/qa/QA_RELEASE_REPORT_[FEATURE_KEY].md`
 - Optional (when detailed test design spec is requested):
@@ -17,10 +21,11 @@ description: QA workflow for SDTK. Use when you need to validate an implemented
 4. Apply `governance/ai/core/SDTK_BENCHMARK_QA_MODE_POLICY.md` for benchmark-mode verdict rules when no executable build exists.
 5. If acceptance criteria / expected behavior is unclear, record OQ-xx in QA report and preserve benchmark-expected ambiguity per `governance/ai/core/SDTK_BENCHMARK_OQ_POLICY.md`; escalate to `@pm` if still missing info.
 6. Execute the required checks, record the commands used, and capture the actual results (unit/integration/e2e or document review evidence as applicable).
-7. Record defects with severity and status.
-8. Decide: APPROVED vs REJECTED only after fresh verification evidence supports the verdict.
-9. Update shared state + Phase 5 checklist.
-10. Handoff: `@pm please finalize release status ...` if approved.
+7. When validating requirement behavior, quote the exact specification text before recording a match or mismatch.
+8. Record defects with severity and status.
+9. Decide: APPROVED vs REJECTED only after fresh verification evidence supports the verdict.
+10. Update shared state + Phase 5 checklist.
+11. Handoff: `@pm please finalize release status ...` if approved.
 
 ## Verification Before Completion
 Apply `governance/ai/core/SDTK_VERIFICATION_BEFORE_COMPLETION_POLICY.md` and require fresh verification evidence before any QA verdict or handoff.
@@ -32,6 +37,14 @@ Do not:
 
 If the environment cannot run the proving checks, follow the benchmark QA mode policy explicitly and state that the result is not fully verified at runtime.
 
+## Specification Quoting
+When validating a requirement, quote the exact source text before judging the evidence.
+
+Use this format:
+- `Spec says: "[exact quote]" -> Evidence: [match/mismatch + file reference]`
+
+Apply it to BA, PRD or BACKLOG, ARCH, API, DB, and flow-action sources whenever they define the expected behavior.
+
 ## Order-Critical Hard Gate
 Do not start QA handoff, release testing, or release decision work until both DEV review gates are documented as PASS:
 - Stage 1 artifact/spec compliance review

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

@@ -5,6 +5,14 @@ description: Create/update screen flow-action specifications from requirement so
 
 # SDTK Screen Flow Action Spec
 
+## 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`
 - Optional supporting docs:
@@ -31,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.
@@ -39,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`
@@ -59,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`
@@ -66,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

@@ -19,12 +19,13 @@ 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`
+3. `Assumptions`
+4. `Screen flow action` (with PlantUML)
+5. `Screen layout spec by flow action`
+6. `System processing flow`
+7. `Open questions`
+8. `Screen - API mapping`
+9. `Document history`
 
 If a section is not in scope, keep the section and mark explicitly as `N/A` with reason.
 
@@ -40,7 +41,34 @@ If a section is not in scope, keep the section and mark explicitly as `N/A` with
 - 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)
+### 3.1 Action Table Mapping Completion Rules
+
+- After API endpoint spec and database spec are available, the action-table columns `Attribute`, `DB Column`, `Size`, and `Default Value` must not be left blank when the mapping can be derived from current source-of-truth inputs.
+- Fill these four columns only after the relevant API contract and DB schema are stable enough to be treated as the current source of truth for the active phase.
+- Source priority for filling the four columns:
+  1. `docs/api/*_ENDPOINTS.md` and OpenAPI YAML for request/response contract
+  2. `docs/database/DATABASE_SPEC_*.md` for physical column names, nullability, storage shape, and query-source aliases
+  3. confirmed flow/business rules for default state and behavior
+  4. design source (Figma/Excel) for screen label and control type only
+- `Attribute` rules:
+  - input item: use the canonical request payload path
+  - display item: use the canonical response path
+  - UI-only item: use `ui.*` namespace
+- `DB Column` rules:
+  - use physical DB column names or query-source aliases from the API/database spec
+  - if multiple columns participate, list them explicitly
+  - if the control is UI-only, write `N/A`
+- `Size` rules:
+  - document data format/type, not pixel width
+  - prefer canonical forms such as `uuid`, `DATE (YYYY-MM-DD)`, `DATETIME`, `TIME (HH:mm)`, `boolean`, `array[uuid]`, `enum(...)`, `JSON string`
+  - prefer DB storage type first; if not available, fall back to API schema type/format
+- `Default Value` rules:
+  - use confirmed business, UI, or runtime defaults
+  - if the default comes from settings or environment, state that clearly
+  - if not finalized, use `TBD` and keep or raise an open-question reference in `Note`
+- If screen labels conflict with canonical API/DB naming, preserve the original screen label in the visible screen columns, but keep `Attribute` and `DB Column` aligned to API/DB source of truth and explain the mismatch in `Note`.
+
+### 3.2 Language and Encoding Standards (EN Artifacts)
 
 - For EN artifacts (`docs/en/**` or explicitly requested EN version), narrative text must be English.
 - JP labels, if provided by the input, should be kept in a clearly marked appendix or note column, not in the default item table columns.
@@ -49,16 +77,24 @@ If a section is not in scope, keep the section and mark explicitly as `N/A` with
 - 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
+### 3.3 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.
 
+### 3.4 Assumptions Section
+
+- Every flow-action spec must include a top-level `## Assumptions` section.
+- Use this table format exactly: `# | Assumption | Verified | Risk if wrong`.
+- Keep assumptions explicit when downstream mapping or behavior depends on an unresolved decision.
+- If an assumption affects UI behavior, API mapping, or DB mapping, reflect the risk in `Note` and keep or raise the related `OQ-xx` item.
+
 ## 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.
+- 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`.
 
@@ -92,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.
@@ -101,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.
 
@@ -112,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
@@ -120,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.
@@ -158,6 +213,7 @@ When `Design Source Type` is `generated-draft`:
 - Numbering is global across the document (no resets).
 - No broken image links (for `generated-draft` screens: `.svg` exists or render-skipped note is present).
 - Screen/API mappings are consistent with `*_ENDPOINTS.md`.
+- Assumptions section exists and unresolved assumptions are traceable.
 - Open questions are explicit and traceable.
 - For EN artifact: no leftover VI text outside allowed `Original Text` appendix blocks.
 - No mojibake/encoding corruption markers.

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`.