sdtk-kit 0.3.9 → 1.0.0

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

@@ -1,220 +0,0 @@
-# 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. `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.
-
-## 3. Table Standards
-
-- Every table must include a `No` column (sequential numbering).
-- Use stable headers for action tables:
-  - `No | 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 / 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 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.
-- 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.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`.
-
-## 5. Screen Section Rules
-
-For each screen section:
-
-- Provide metadata:
-  - official screen name
-  - Screen ID
-  - Design Source Type
-  - Design Source Reference
-- Embed one representative image per screen (from Figma, screenshot, or generated layout).
-- 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.
-
-## 5.1 Design Source Modes
-
-Each screen section must declare a design source using one of these modes:
-
-| Mode | When | Design Source Reference |
-|------|------|----------------------|
-| `source-backed` | Figma URL or screenshot is available | Figma URL or screenshot path |
-| `generated-draft` | No Figma/screenshot, but feature has UI scope | Section reference in `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md` |
-| `none` | Feature has no UI scope for this screen | State `N/A - no UI scope` |
-
-Rules:
-- For UI-scope features, `none` is only valid when the specific screen truly has no visual layout.
-- When using `generated-draft`, the `DESIGN_LAYOUT_[FEATURE_KEY].md` must exist before the flow-action spec is finalized.
-- 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.
-- 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 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.
-
-## 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 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
-
-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 (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.
-
-## 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 (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.
-- Headings/tables are structurally clean (no merged lines that break readability/traceability).

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

@@ -1,128 +0,0 @@
-# YAML CREATION RULES FINAL
-
-This file is the canonical rule set for designing and maintaining feature-level OpenAPI YAML.
-
-Use this file for:
-- OpenAPI YAML contract design
-- endpoint path/method decisions
-- request/response schema design
-- endpoint summary and contract consistency checks
-
-Do not use this file as the primary rule source for:
-- flowchart writing details
-- API design detail markdown layout
-
-Use `API_DESIGN_FLOWCHART_CREATION_RULES_FINAL.md` for those.
-
-## 1. Rule Precedence
-- Priority 1: follow the existing system's real route, method, payload, and response conventions.
-- Priority 2: match the current source code and runtime behavior.
-- Priority 3: apply the reusable standards in this document.
-- If a reusable rule conflicts with the target system, keep the system rule and document the exception explicitly.
-
-## 2. API Scope Classification
-- Every endpoint must be classified as one of:
-  - `New`
-  - `Deferred`
-  - `Existing (reuse)`
-- Do not silently create a new feature-local API if an existing system API already provides the same behavior with a compatible contract.
-- If the existing API is close in purpose but payload or response is incompatible with the feature need, create a bounded new API.
-
-## 3. Endpoint Path Design
-- Use singular resource names in endpoint paths.
-- Use explicit action segments only when needed by system convention:
-  - `list`
-  - `search`
-  - `edit`
-  - `delete`
-  - `multi-create`
-- Prefer stable system-style patterns such as:
-  - list: `GET /{resource}/list/{company_uuid}/{parent_uuid}`
-  - search: `POST /{resource}/search/{company_uuid}`
-  - view-specific search: `POST /{resource}/bukken-view/search/{company_uuid}`
-  - create: `POST /{resource}/{company_uuid}`
-  - detail: `GET /{resource}/{company_uuid}/{resource_uuid}`
-  - edit: `POST /{resource}/edit/{company_uuid}/{resource_uuid}`
-  - delete: `POST /{resource}/delete/{company_uuid}/{resource_uuid}`
-- Separate namespaces by bounded context.
-- Do not repeat namespace meaning in child path segments.
-
-## 4. Request Contract Rules
-- For feature-owned POST search and write APIs, prefer a stable wrapper:
-  - `data: { ... }`
-- For complex filters, place fields under:
-  - `data.info`
-- If reusing an existing system API, keep the owning module's contract shape exactly as-is.
-- Do not force reused APIs into the feature wrapper pattern.
-- If a payload field changes behavior, the field must be explicit in the schema and must not remain only in examples.
-
-## 5. Response Contract Rules
-- Success responses must include `status` at minimum.
-- Create APIs should return the minimum new identifier required by the caller.
-  - Example: `status + sagyo_assign_uuid`
-- Edit and delete APIs should return status-only unless the target system has a stronger standard.
-- Pre-check or validation helper APIs should return only the minimum boolean or status needed by the UI.
-  - Do not return detail payloads the UI does not consume.
-- Do not add FE-only visual helper payloads when the client can derive them safely.
-  - Example: remove `timeline_backgrounds` if the frontend renders timeline lines from existing data.
-
-## 6. Naming and Field Mapping Rules
-- Use canonical business-domain terminology from the system glossary and database.
-- Prefer actual system terms such as:
-  - `bukken`
-  - `sagyo`
-  - `sagyoin`
-  - `certification`
-- Avoid legacy aliases when an official term already exists.
-- Field names should align with database semantics when they represent the same concept.
-- If the DB uses a string state code, the API field must not be modeled as an integer.
-- If a field is date-only (`format: date`), include the display format in the description.
-  - Example: `Start date (YYYYMMDD)`
-
-## 7. Search and List API Rules
-- One search API may serve multiple UI actions when the logic is the same:
-  - initial load
-  - search button
-  - refresh after mode/date change
-- If one endpoint serves multiple UI actions, document that explicitly in YAML description and endpoint docs.
-- Search APIs must define filter combination semantics clearly:
-  - AND across different fields
-  - OR within each `*_uuids` array
-- If UI rendering depends on stable order, the YAML description must state the confirmed ORDER BY logic.
-
-## 8. Split vs Reuse Rules
-- Split read/search endpoints when the FE needs materially different grouped or view-shaped datasets.
-- Merge or remove helper payloads when they add maintenance cost without business value.
-- Reuse existing platform APIs when behavior already exists and only a feature-level mapping layer is needed.
-  - Example: reuse shared environment setting APIs instead of creating feature-local setting APIs.
-
-## 9. Sample Data Rules
-- For fields declared as `format: uuid`, use canonical UUID samples.
-  - Example: `123e4567-e89b-12d3-a456-426614174000`
-- Do not use placeholder UUID-like labels such as:
-  - `customer-uuid-001`
-  - `assign-uuid-001`
-- Keep sample data deterministic and internally consistent across request and response examples.
-
-## 10. Cross-Artifact Consistency Rules
-- The YAML contract is the source of truth for:
-  - endpoint path
-  - method
-  - request wrapper
-  - response shape
-- After any YAML contract change, sync these artifacts:
-  - endpoint markdown
-  - flow list
-  - PlantUML flow assets
-  - API design detail markdown
-- If any artifact cannot yet be synced, note the mismatch explicitly rather than leaving stale content.
-
-## 11. Minimum YAML Quality Gate
-- Path/method follow the target system convention.
-- API type is classified (`New`, `Deferred`, `Existing (reuse)`).
-- Request/response wrappers are stable and explicit.
-- FE-only helper payloads are removed.
-- Field names and types match DB semantics.
-- UUID examples are valid UUIDs.
-- Date descriptions include display format where needed.
-- Search/list APIs document filter semantics and ordering when relevant.

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

@@ -1,29 +0,0 @@
----
-name: sdtk-ba
-description: Business Analyst workflow for SDTK. Use when you need to turn PM initiation into BA_SPEC with glossary, business rules (BR-xx), use cases (UC-xx), acceptance criteria (AC-xx), NFRs, risks, open questions, and a traceability matrix.
----
-
-# 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`
-
-## Process
-1. Read `docs/product/PROJECT_INITIATION_[FEATURE_KEY].md` and any source requirements.
-2. Produce:
-   - Glossary
-   - BR-xx (numbered)
-   - UC-xx (cover 100% REQ-xx)
-   - AC-xx (mapped to UC/BR)
-   - NFR-xx
-   - Risks + Open Questions
-   - Traceability summary table (REQ -> UC/BR/AC)
-3. If source requirements are VI/JP, preserve the original text and add a literal EN translation in appendices.
-4. For benchmark runs, apply `governance/ai/core/SDTK_BENCHMARK_OQ_POLICY.md`: keep benchmark-expected open questions explicitly OPEN and do not silently resolve them in BA output.
-5. If anything is unclear, record OQ-xx in BA_SPEC "Open Questions" and escalate to `@pm` for a decision.
-6. Update `SHARED_PLANNING.md` and `QUALITY_CHECKLIST.md` Phase 2.
-7. Handoff: `@pm specs ready for PRD`.

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

@@ -1,52 +0,0 @@
----
-name: sdtk-design-layout
-description: Generate UI screen layout documentation for a feature, including PlantUML @startsalt wireframes and item tables. Use when a feature includes frontend/admin screens and you need docs/design/* deliverables.
----
-
-# 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, with visible screen-local markers embedded directly in the SALT labels
-   - API list table
-   - 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
-- Script: `toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py`
-- Usage:
-  ```
-  python "toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py" \
-    --design-layout "docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md" \
-    --feature-key [FEATURE_KEY]
-  ```
-- Requires: Java + `plantuml.jar` (auto-detected from VSCode PlantUML extension, or pass `--plantuml-jar`)
-- Output: `.svg` files under `docs/specs/assets/<feature_snake>/screens/`
-- Failure policy: non-blocking. Warns and continues if rendering is unavailable.
-
-## 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

@@ -1,246 +0,0 @@
-#!/usr/bin/env python3
-"""
-Render screen preview SVGs from DESIGN_LAYOUT PlantUML SALT wireframes.
-
-Extracts @startsalt blocks from a DESIGN_LAYOUT_[FEATURE_KEY].md file,
-renders each to .svg using a local plantuml.jar, and writes the images
-to docs/specs/assets/<feature_snake>/screens/.
-
-Graceful failure: if PlantUML is unavailable or a block fails to render,
-the script warns but does not exit with an error code.
-"""
-
-from __future__ import annotations
-
-import argparse
-import re
-import shutil
-import subprocess
-import sys
-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."
-    )
-    parser.add_argument(
-        "--design-layout",
-        required=True,
-        help="Path to DESIGN_LAYOUT_[FEATURE_KEY].md",
-    )
-    parser.add_argument(
-        "--feature-key",
-        required=True,
-        help="Feature key, e.g. CRM_LITE",
-    )
-    parser.add_argument(
-        "--output-dir",
-        default="",
-        help="Output directory for SVGs. Default: docs/specs/assets/<feature_snake>/screens/",
-    )
-    parser.add_argument(
-        "--plantuml-jar",
-        default="",
-        help="Explicit path to plantuml.jar. Auto-detected if omitted.",
-    )
-    parser.add_argument(
-        "--skip-render",
-        action="store_true",
-        help="Extract .puml files only, skip SVG rendering.",
-    )
-    return parser.parse_args()
-
-
-def normalize_feature_snake(feature_key: str) -> str:
-    return re.sub(r"[^a-z0-9]+", "_", feature_key.lower()).strip("_")
-
-
-def find_plantuml_jar(explicit: str) -> Optional[Path]:
-    if explicit:
-        p = Path(explicit).expanduser().resolve()
-        return p if p.exists() else None
-    user_home = Path.home()
-    candidates = sorted(
-        (user_home / ".vscode" / "extensions").glob("jebbs.plantuml-*/plantuml.jar")
-    )
-    if candidates:
-        return candidates[-1]
-    return None
-
-
-def extract_screens(text: str) -> List[Tuple[str, str]]:
-    """Extract (screen_id, plantuml_block) pairs from DESIGN_LAYOUT markdown.
-
-    Looks for heading patterns like '## A-1. Screen Name' or '## SCR-01 Screen Name'
-    followed by a fenced plantuml block containing @startsalt.
-    """
-    screens: List[Tuple[str, str]] = []
-    heading_pattern = re.compile(
-        r"^##\s+([A-Z]+-?\d+|SCR-?\d+)[.\s]",
-        re.MULTILINE,
-    )
-    salt_pattern = re.compile(
-        r"```plantuml\s*\n(@startsalt[\s\S]*?@endsalt)\s*\n```",
-        re.MULTILINE,
-    )
-
-    headings = list(heading_pattern.finditer(text))
-    for i, match in enumerate(headings):
-        screen_id = match.group(1).strip().lower().replace("-", "_")
-        start = match.start()
-        end = headings[i + 1].start() if i + 1 < len(headings) else len(text)
-        section = text[start:end]
-
-        salt_match = salt_pattern.search(section)
-        if salt_match:
-            screens.append((screen_id, salt_match.group(1)))
-
-    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", "-Dfile.encoding=UTF-8", "-jar", str(plantuml_jar), "-charset", "UTF-8", "-tsvg", str(puml_path)],
-        stdout=subprocess.PIPE,
-        stderr=subprocess.STDOUT,
-        text=True,
-        check=False,
-    )
-    # PlantUML writes .svg next to the .puml file.
-    svg_path = puml_path.with_suffix(".svg")
-    if not svg_path.exists():
-        return f"Render failed (no svg produced): {puml_path.name}"
-
-    # If .puml is already in the output dir, no copy needed.
-    # Otherwise move the svg to the output dir.
-    svg_dst = output_dir / svg_path.name
-    if svg_path.resolve() != svg_dst.resolve():
-        shutil.copy2(svg_path, svg_dst)
-        svg_path.unlink(missing_ok=True)
-        svg_path = svg_dst
-
-    svg_text = svg_path.read_text(encoding="utf-8", errors="ignore")
-    if any(
-        x in svg_text
-        for x in ("Cannot find group", "Syntax Error", "contains errors")
-    ):
-        return f"Rendered with error content: {svg_path.name}"
-    if proc.returncode != 0:
-        return f"PlantUML exit={proc.returncode} for {puml_path.name}"
-    return None
-
-
-def main() -> int:
-    args = parse_args()
-
-    feature_key = args.feature_key.strip()
-    if not feature_key:
-        print("[ERROR] --feature-key is empty", file=sys.stderr)
-        return 1
-
-    feature_snake = normalize_feature_snake(feature_key)
-    layout_path = Path(args.design_layout)
-    if not layout_path.exists():
-        print(f"[ERROR] Design layout not found: {layout_path}", file=sys.stderr)
-        return 1
-
-    if args.output_dir:
-        output_dir = Path(args.output_dir)
-    else:
-        output_dir = Path(f"docs/specs/assets/{feature_snake}/screens")
-
-    output_dir.mkdir(parents=True, exist_ok=True)
-
-    text = layout_path.read_text(encoding="utf-8")
-    screens = extract_screens(text)
-
-    if not screens:
-        print("[WARN] No screen sections with @startsalt blocks found.")
-        print("[OK] Nothing to render.")
-        return 0
-
-    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:
-        puml_name = f"{screen_id}.puml"
-        puml_path = output_dir / puml_name
-        puml_path.write_text(salt_block + "\n", encoding="utf-8")
-        puml_files.append(puml_path)
-
-    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
-    jar = find_plantuml_jar(args.plantuml_jar)
-    if not jar:
-        print("[WARN] PlantUML jar not found. SVG rendering skipped.")
-        print("       Use --plantuml-jar or install VSCode PlantUML extension.")
-        print(f"[OK] Wrote {len(puml_files)} .puml file(s) without SVG rendering.")
-        return 0
-
-    # Render SVGs
-    errors: List[str] = []
-    rendered = 0
-    for puml_path in puml_files:
-        err = render_svg(jar, puml_path, output_dir)
-        if err:
-            errors.append(err)
-        else:
-            rendered += 1
-
-    print(f"[OK] Rendered {rendered}/{len(puml_files)} screen image(s) to: {output_dir}")
-    if errors:
-        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
-
-
-if __name__ == "__main__":
-    try:
-        raise SystemExit(main())
-    except Exception as exc:
-        print(f"[ERROR] {exc}", file=sys.stderr)
-        raise