sdtk-kit 0.3.7 → 0.3.9

package/assets/toolkit/toolkit/install.ps1

@@ -58,6 +58,46 @@ function Copy-File {
   Copy-Item -LiteralPath $SourcePath -Destination $DestinationPath -Force
 }
 
+function Install-ClaudeSkillDirectory {
+  param(
+    [Parameter(Mandatory = $true)][System.IO.DirectoryInfo]$SkillDir,
+    [Parameter(Mandatory = $true)][string]$SkillsDest,
+    [Parameter(Mandatory = $true)][string]$ToolkitRoot,
+    [Parameter(Mandatory = $true)][bool]$Overwrite
+  )
+
+  $destDir = Join-Path $SkillsDest $SkillDir.Name
+  if (Test-Path -LiteralPath $destDir) {
+    if (-not $Overwrite) {
+      Write-Warning "Already exists (skipping). Use -Force to overwrite: $destDir"
+      return $true
+    }
+    Remove-Item -LiteralPath $destDir -Recurse -Force
+  }
+
+  $parent = Split-Path -Parent $destDir
+  if ($parent -and -not (Test-Path -LiteralPath $parent)) {
+    New-Item -ItemType Directory -Force -Path $parent | Out-Null
+  }
+  Copy-Item -LiteralPath $SkillDir.FullName -Destination $destDir -Recurse -Force
+
+  $canonicalSkillDir = Join-Path $ToolkitRoot "skills/sdtk-$($SkillDir.Name)"
+  foreach ($subDirName in @('scripts', 'prompts')) {
+    $srcSubDir = Join-Path $canonicalSkillDir $subDirName
+    $destSubDir = Join-Path $destDir $subDirName
+    if (-not (Test-Path -LiteralPath $srcSubDir)) {
+      continue
+    }
+
+    if (Test-Path -LiteralPath $destSubDir) {
+      Remove-Item -LiteralPath $destSubDir -Recurse -Force
+    }
+    Copy-Item -LiteralPath $srcSubDir -Destination $destSubDir -Recurse -Force
+  }
+
+  return $true
+}
+
 function Install-RuntimeAdapter {
   param(
     [Parameter(Mandatory = $true)][string]$ToolkitRoot,
@@ -102,9 +142,9 @@ function Install-ClaudeSkills {
     $srcFile = Join-Path $skillDir.FullName 'SKILL.md'
     if (-not (Test-Path -LiteralPath $srcFile)) { continue }
 
-    $destFile = Join-Path $skillsDest "$($skillDir.Name)/SKILL.md"
-    Copy-File -SourcePath $srcFile -DestinationPath $destFile -Overwrite $Overwrite
-    $skillCount++
+    if (Install-ClaudeSkillDirectory -SkillDir $skillDir -SkillsDest $skillsDest -ToolkitRoot $ToolkitRoot -Overwrite $Overwrite) {
+      $skillCount++
+    }
   }
 
   # Install reference files
@@ -267,4 +307,4 @@ if (-not $Quiet) {
   }
   Write-Host '3) Generate feature docs:'
   Write-Host '   sdtk generate --feature-key YOUR_FEATURE --feature-name "Your Feature"'
-}
+}

package/assets/toolkit/toolkit/scripts/install-claude-skills.ps1

@@ -34,6 +34,46 @@ function Copy-File {
   Copy-Item -LiteralPath $SourcePath -Destination $DestinationPath -Force
 }
 
+function Install-ClaudeSkillDirectory {
+  param(
+    [Parameter(Mandatory = $true)][System.IO.DirectoryInfo]$SkillDir,
+    [Parameter(Mandatory = $true)][string]$SkillsDest,
+    [Parameter(Mandatory = $true)][string]$ToolkitRoot,
+    [Parameter(Mandatory = $true)][bool]$Overwrite
+  )
+
+  $destDir = Join-Path $SkillsDest $SkillDir.Name
+  if (Test-Path -LiteralPath $destDir) {
+    if (-not $Overwrite) {
+      Write-Warning "Already exists (skipping). Use -Force to overwrite: $destDir"
+      return $true
+    }
+    Remove-Item -LiteralPath $destDir -Recurse -Force
+  }
+
+  $parent = Split-Path -Parent $destDir
+  if ($parent -and -not (Test-Path -LiteralPath $parent)) {
+    New-Item -ItemType Directory -Force -Path $parent | Out-Null
+  }
+  Copy-Item -LiteralPath $SkillDir.FullName -Destination $destDir -Recurse -Force
+
+  $canonicalSkillDir = Join-Path $ToolkitRoot "skills/sdtk-$($SkillDir.Name)"
+  foreach ($subDirName in @('scripts', 'prompts')) {
+    $srcSubDir = Join-Path $canonicalSkillDir $subDirName
+    $destSubDir = Join-Path $destDir $subDirName
+    if (-not (Test-Path -LiteralPath $srcSubDir)) {
+      continue
+    }
+
+    if (Test-Path -LiteralPath $destSubDir) {
+      Remove-Item -LiteralPath $destSubDir -Recurse -Force
+    }
+    Copy-Item -LiteralPath $srcSubDir -Destination $destSubDir -Recurse -Force
+  }
+
+  return $true
+}
+
 $toolkitRoot = Resolve-Path (Join-Path $PSScriptRoot '..')
 
 # Resolve destination based on scope
@@ -59,9 +99,9 @@ foreach ($skillDir in (Get-ChildItem -Path $skillsSource -Directory)) {
   $srcFile = Join-Path $skillDir.FullName 'SKILL.md'
   if (-not (Test-Path -LiteralPath $srcFile)) { continue }
 
-  $destFile = Join-Path $skillsDest "$($skillDir.Name)/SKILL.md"
-  Copy-File -SourcePath $srcFile -DestinationPath $destFile -Overwrite ([bool]$Force)
-  $skillCount++
+  if (Install-ClaudeSkillDirectory -SkillDir $skillDir -SkillsDest $skillsDest -ToolkitRoot $toolkitRoot -Overwrite ([bool]$Force)) {
+    $skillCount++
+  }
 }
 
 # Install reference files

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

@@ -5,6 +5,10 @@ description: Generate detailed API design markdown (`[FEATURE_KEY]_API_DESIGN_DE
 
 # 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 or missing assumptions in the API design detail.
+
 ## Outputs
 - `docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md`
 - Supporting generated assets:
@@ -32,7 +36,7 @@ description: Generate detailed API design markdown (`[FEATURE_KEY]_API_DESIGN_DE
 ## 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 (`@startuml ... @enduml`) and map 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)

package/assets/toolkit/toolkit/skills/sdtk-api-design-spec/references/API_DESIGN_CREATION_RULES.md

@@ -7,10 +7,16 @@ The active rule source for API design detail and API flowchart behavior is now:
 - `API_DESIGN_FLOWCHART_CREATION_RULES_FINAL.md` (root)
 - `templates/docs/api/API_DESIGN_FLOWCHART_CREATION_RULES.md` (toolkit)
 
-Use that file for:
+Even in compatibility mode, generated API design detail docs must still include:
+- a top-level `## Assumptions` section
+- this table format: `| # | Assumption | Verified | Risk if wrong |`
+- explicit unresolved assumptions when downstream review depends on them
+
+Use the active rule file for:
 - API design detail markdown structure
 - flowchart integration and synchronization rules
 - error section rules
 - flow summary / notes / login rules
+- assumptions-section requirements
 
 This compatibility note should remain only until all references are migrated.

package/assets/toolkit/toolkit/skills/sdtk-api-design-spec/references/API_DESIGN_FLOWCHART_CREATION_RULES.md

@@ -38,6 +38,23 @@ Primary sample references:
 - `GET /bukken/info/{company_uuid}/{bukken_uuid}` style
 - search API query-builder style shown in the Bukken sample helper flow
 
+## 2.1 API Design Detail Markdown Requirements
+
+Generated `*_API_DESIGN_DETAIL.md` files must keep this minimum structure:
+- `## 0. Abbreviations`
+- `## 1. Document Scope`
+- `## Assumptions`
+- per-endpoint `## <n>. API Detail ...` sections
+- `## 3. Generation Notes` or the current equivalent final notes section
+
+`## Assumptions` must use this table shape:
+
+```text
+| # | Assumption | Verified | Risk if wrong |
+```
+
+If an assumption is not verified yet, keep it explicit and treat it as a downstream review risk instead of silently collapsing it into a fact.
+
 ## 3. Core Flowchart Writing Rules
 
 ### Rule A. Add a visible API header for every block

package/assets/toolkit/toolkit/skills/sdtk-api-design-spec/scripts/generate_api_design_detail.py

@@ -53,6 +53,49 @@ def normalize_feature_snake(feature_key: str) -> str:
     return re.sub(r"[^a-z0-9]+", "_", feature_key.lower()).strip("_")
 
 
+def collect_server_prefixes(spec: dict) -> List[str]:
+    prefixes: List[str] = []
+    for server in spec.get("servers", []) or []:
+        url = str((server or {}).get("url", "")).strip()
+        if not url:
+            continue
+        if "://" in url:
+            match = re.match(r"https?://[^/]+(?P<path>/.*)?", url)
+            url = match.group("path") if match and match.group("path") else "/"
+        if not url.startswith("/"):
+            continue
+        normalized = re.sub(r"/{2,}", "/", url).rstrip("/")
+        if normalized:
+            prefixes.append(normalized)
+    return sorted(set(prefixes), key=len, reverse=True)
+
+
+def normalize_match_path(path: str, server_prefixes: List[str]) -> str:
+    normalized = path.strip()
+    if "://" in normalized:
+        match = re.match(r"https?://[^/]+(?P<path>/.*)?", normalized)
+        normalized = match.group("path") if match and match.group("path") else "/"
+    normalized = normalized.split("?", maxsplit=1)[0].strip()
+    if not normalized.startswith("/"):
+        normalized = "/" + normalized
+    normalized = re.sub(r"/{2,}", "/", normalized)
+
+    for prefix in server_prefixes:
+        if normalized == prefix:
+            normalized = "/"
+            break
+        if normalized.startswith(prefix + "/"):
+            normalized = normalized[len(prefix) :]
+            break
+
+    if not normalized.startswith("/"):
+        normalized = "/" + normalized
+    if len(normalized) > 1:
+        normalized = normalized.rstrip("/")
+    normalized = re.sub(r"\{[^/]+\}", "{}", normalized)
+    return normalized
+
+
 def parse_include_filters(raw_filters: List[str]) -> List[Tuple[Optional[str], str]]:
     parsed: List[Tuple[Optional[str], str]] = []
     for raw in raw_filters:
@@ -99,18 +142,30 @@ def collect_operations(spec: dict, include_filters: List[Tuple[Optional[str], st
     return operations
 
 
-def collect_flow_map(flow_text: str) -> Dict[Tuple[str, str], str]:
-    flow_map: Dict[Tuple[str, str], str] = {}
+def extract_flow_signature(block: str, server_prefixes: List[str]) -> Tuple[Optional[str], Optional[str]]:
+    patterns = [
+        r'partition\s+"API:\s*([A-Z]+)\s+(\S+)(?:\s{2,}.*?)?"\s*\{',
+        r'partition\s+"([A-Z]+)\s+\*\*(.*?)\*\*',
+        r'partition\s+"API:\s*([A-Z]+)\s+\*\*(.*?)\*\*',
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, block)
+        if not match:
+            continue
+        method = match.group(1).lower().strip()
+        path = normalize_match_path(match.group(2), server_prefixes)
+        return method, path
+    return None, None
+
+
+def collect_flow_blocks(flow_text: str, server_prefixes: List[str]) -> List[Tuple[Optional[str], Optional[str], str]]:
+    blocks_with_meta: List[Tuple[Optional[str], Optional[str], str]] = []
     blocks = re.findall(r"@startuml[\s\S]*?@enduml", flow_text)
     for block in blocks:
-        m = re.search(r'partition\s+"([A-Z]+)\s+\*\*(.*?)\*\*', block)
-        if not m:
-            continue
-        method = m.group(1).lower().strip()
-        path = m.group(2).strip()
         sanitized = re.sub(r";<<#[^>]+>>", ";", block.strip())
-        flow_map[(method, path)] = sanitized + "\n"
-    return flow_map
+        method, path = extract_flow_signature(sanitized, server_prefixes)
+        blocks_with_meta.append((method, path, sanitized + "\n"))
+    return blocks_with_meta
 
 
 def slugify(text: str) -> str:
@@ -435,13 +490,19 @@ def main() -> int:
     images_dir = Path(args.images_dir)
 
     spec = load_yaml(yaml_path)
+    server_prefixes = collect_server_prefixes(spec)
     include_filters = parse_include_filters(args.include)
     operations = collect_operations(spec, include_filters)
     if not operations:
         raise RuntimeError("No API operations selected from YAML")
 
-    flow_map = collect_flow_map(flow_path.read_text(encoding="utf-8"))
+    flow_blocks = collect_flow_blocks(flow_path.read_text(encoding="utf-8"), server_prefixes)
+    flow_map: Dict[Tuple[str, str], str] = {}
+    for block_method, block_path, block_text in flow_blocks:
+        if block_method and block_path and (block_method, block_path) not in flow_map:
+            flow_map[(block_method, block_path)] = block_text
     missing_flows: List[str] = []
+    order_fallbacks: List[str] = []
 
     flows_dir.mkdir(parents=True, exist_ok=True)
     images_dir.mkdir(parents=True, exist_ok=True)
@@ -481,7 +542,18 @@ def main() -> int:
         svg_rel = Path(os.path.relpath(svg_path, output_path.parent))
         desc_sections = parse_description_sections(str(op.get("description", "")))
 
-        flow = flow_map.get((method, path))
+        normalized_path = normalize_match_path(path, server_prefixes)
+        flow = flow_map.get((method, normalized_path))
+        if not flow and len(flow_blocks) == len(operations):
+            candidate_method, candidate_path, candidate_flow = flow_blocks[i - 1]
+            flow = candidate_flow
+            if candidate_method and candidate_path and (candidate_method != method or candidate_path != normalized_path):
+                order_fallbacks.append(
+                    f"{method.upper()} {path} -> used block {i} by order fallback despite signature mismatch "
+                    f"({candidate_method.upper()} {candidate_path})"
+                )
+            else:
+                order_fallbacks.append(f"{method.upper()} {path} -> used block {i} by order fallback")
         if not flow:
             missing_flows.append(f"{method.upper()} {path}")
             flow = (
@@ -638,6 +710,10 @@ def main() -> int:
         print("[WARN] Missing flow blocks:")
         for item in missing_flows:
             print(f"  - {item}")
+    if order_fallbacks:
+        print("[WARN] Flow block order fallback used:")
+        for item in order_fallbacks:
+            print(f"  - {item}")
     if render_errors:
         print("[WARN] Render issues:")
         for item in render_errors:

package/assets/toolkit/toolkit/skills/sdtk-api-doc/SKILL.md

@@ -5,6 +5,10 @@ description: Generate OpenAPI 3.x YAML and PlantUML flow diagrams for a feature
 
 # SDTK API Documentation
 
+## Critical Constraints
+- I do not invent API paths or payload contracts that contradict BA or ARCH artifacts.
+- I do not leave YAML, endpoint markdown, and flow-list outputs out of sync.
+
 ## Outputs
 - `docs/api/[FeaturePascal]_API.yaml`
 - `docs/api/[FEATURE_KEY]_ENDPOINTS.md`

package/assets/toolkit/toolkit/skills/sdtk-api-doc/references/API_DESIGN_FLOWCHART_CREATION_RULES.md

@@ -38,6 +38,23 @@ Primary sample references:
 - `GET /bukken/info/{company_uuid}/{bukken_uuid}` style
 - search API query-builder style shown in the Bukken sample helper flow
 
+## 2.1 API Design Detail Markdown Requirements
+
+Generated `*_API_DESIGN_DETAIL.md` files must keep this minimum structure:
+- `## 0. Abbreviations`
+- `## 1. Document Scope`
+- `## Assumptions`
+- per-endpoint `## <n>. API Detail ...` sections
+- `## 3. Generation Notes` or the current equivalent final notes section
+
+`## Assumptions` must use this table shape:
+
+```text
+| # | Assumption | Verified | Risk if wrong |
+```
+
+If an assumption is not verified yet, keep it explicit and treat it as a downstream review risk instead of silently collapsing it into a fact.
+
 ## 3. Core Flowchart Writing Rules
 
 ### Rule A. Add a visible API header for every block

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

@@ -5,6 +5,10 @@ description: Solution Architect workflow for SDTK. Use when you need to convert
 
 # SDTK ARCH (Solution Architecture)
 
+## Critical Constraints
+- I do not generate `FLOW_ACTION_SPEC` before `DESIGN_LAYOUT` for UI-scope features.
+- I do not let API, DB, and UI artifacts drift from the same BA and PM source of truth.
+
 ## Outputs
 - `docs/architecture/ARCH_DESIGN_[FEATURE_KEY].md`
 - If applicable:

package/assets/toolkit/toolkit/skills/sdtk-arch/references/API_DESIGN_CREATION_RULES.md

@@ -7,10 +7,16 @@ The active rule source for API design detail and API flowchart behavior is now:
 - `API_DESIGN_FLOWCHART_CREATION_RULES_FINAL.md` (root)
 - `templates/docs/api/API_DESIGN_FLOWCHART_CREATION_RULES.md` (toolkit)
 
-Use that file for:
+Even in compatibility mode, generated API design detail docs must still include:
+- a top-level `## Assumptions` section
+- this table format: `| # | Assumption | Verified | Risk if wrong |`
+- explicit unresolved assumptions when downstream review depends on them
+
+Use the active rule file for:
 - API design detail markdown structure
 - flowchart integration and synchronization rules
 - error section rules
 - flow summary / notes / login rules
+- assumptions-section requirements
 
 This compatibility note should remain only until all references are migrated.

package/assets/toolkit/toolkit/skills/sdtk-arch/references/API_DESIGN_FLOWCHART_CREATION_RULES.md

@@ -38,6 +38,23 @@ Primary sample references:
 - `GET /bukken/info/{company_uuid}/{bukken_uuid}` style
 - search API query-builder style shown in the Bukken sample helper flow
 
+## 2.1 API Design Detail Markdown Requirements
+
+Generated `*_API_DESIGN_DETAIL.md` files must keep this minimum structure:
+- `## 0. Abbreviations`
+- `## 1. Document Scope`
+- `## Assumptions`
+- per-endpoint `## <n>. API Detail ...` sections
+- `## 3. Generation Notes` or the current equivalent final notes section
+
+`## Assumptions` must use this table shape:
+
+```text
+| # | Assumption | Verified | Risk if wrong |
+```
+
+If an assumption is not verified yet, keep it explicit and treat it as a downstream review risk instead of silently collapsing it into a fact.
+
 ## 3. Core Flowchart Writing Rules
 
 ### Rule A. Add a visible API header for every block

package/assets/toolkit/toolkit/skills/sdtk-arch/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-ba/SKILL.md

@@ -5,6 +5,10 @@ description: Business Analyst workflow for SDTK. Use when you need to turn PM in
 
 # SDTK BA (Business Analysis)
 
+## Critical Constraints
+- I do not mark BA analysis complete until `REQ`, `UC`, `BR`, and `AC` traceability is explicit.
+- I do not silently resolve business ambiguities that belong to PM or the user.
+
 ## Output
 - `docs/specs/BA_SPEC_[FEATURE_KEY].md`
 

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

@@ -5,19 +5,35 @@ description: Generate UI screen layout documentation for a feature, including Pl
 
 # SDTK Screen Layout Design
 
+## 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`
 
 ## 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
@@ -34,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.
-