sdtk-kit 0.3.7 → 0.3.9

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

@@ -1,36 +1,30 @@
 ---
 name: arch
-description: Solution Architect workflow for SDTK. Use when you need to convert BA_SPEC + PM backlog into technical architecture, API contracts (OpenAPI), and UI layout docs; update SHARED_PLANNING.md / QUALITY_CHECKLIST.md and handoff to DEV.
+description: Solution Architect workflow for SDTK. Use when you need to convert BA_SPEC plus PM backlog into technical architecture, API contracts, and UI design docs; then hand off to DEV.
 ---
 
 ## SDTK Pipeline Rules (always apply)
 1. Pipeline: PM Initiation -> BA Analysis -> PM Planning -> Architecture Design -> Development + Review -> QA Validation
-2. After completing phase work: update SHARED_PLANNING.md + QUALITY_CHECKLIST.md
-3. If unclear: log OQ-xx in artifact, escalate to PM
+2. After completing phase work: update SHARED_PLANNING.md and QUALITY_CHECKLIST.md
+3. If unclear: log OQ-xx in artifact and escalate to PM
 4. Traceability: REQ -> BR/UC/AC -> design -> backlog -> code/tests -> QA
-5. Code review must be COMPLETE before QA phase can start
+5. Code review must be complete before QA phase can start
 6. Do not skip phases. If inputs are missing, ask focused questions.
 
 ## Prerequisites (verify before proceeding)
 Read QUALITY_CHECKLIST.md and verify:
-- Phase 2 BA Analysis gate must show all items [x] Done.
-- Phase 2+ PM Planning gate must show all items [x] Done.
-
-If prerequisites are not met, report which gate is missing and suggest user run the prerequisite phase first.
-
-## Current Context
-- Config: !`node -e "try{process.stdout.write(require('fs').readFileSync('sdtk.config.json','utf8'))}catch{process.stdout.write('{}')}"`
-- Pipeline: !`node -e "try{process.stdout.write(require('fs').readFileSync('SHARED_PLANNING.md','utf8'))}catch{process.stdout.write('Not initialized')}"`
-- Gates: !`node -e "try{process.stdout.write(require('fs').readFileSync('QUALITY_CHECKLIST.md','utf8'))}catch{process.stdout.write('Not initialized')}"`
-- State: !`node -e "try{process.stdout.write(require('fs').readFileSync('.sdtk/orchestration-state.json','utf8'))}catch{process.stdout.write('{}')}"`
+- Phase 2 BA Analysis gate must show all items done
+- Phase 2+ PM Planning gate must show all items done
 
 ## Input
 $ARGUMENTS
 
-If no arguments are provided, read current feature context from SHARED_PLANNING.md.
-
 # SDTK ARCH (Solution Architecture)
 
+## Critical Constraints
+- I do not generate `FLOW_ACTION_SPEC` before `DESIGN_LAYOUT` for UI-scope features.
+- I do not silently skip render failures for generated-draft screen images.
+
 ## Outputs
 - `docs/architecture/ARCH_DESIGN_[FEATURE_KEY].md`
 - If applicable:
@@ -44,29 +38,22 @@ If no arguments are provided, read current feature context from SHARED_PLANNING.
 
 ## Process
 1. Read BA spec and PRD/backlog.
-2. Read `sdtk.config.json` for project stack assumptions (backend/frontend/db/auth).
-3. If architecture output includes API contracts/flows, read and apply:
+2. Read `sdtk.config.json` for project stack assumptions.
+3. If architecture output includes API contracts or flows, read and apply:
    - `.claude/skills/references/YAML_CREATION_RULES.md`
    - `.claude/skills/references/API_DESIGN_FLOWCHART_CREATION_RULES.md`
-   - `governance/ai/core/SDTK_API_PATH_STYLE_POLICY.md` for canonical resource naming and multi-word path style
 4. If architecture output includes screen flow-action specs, read and apply `.claude/skills/references/FLOW_ACTION_SPEC_CREATION_RULES.md`.
-5. If API detail spec is required, use `/api-design-spec` to build/update `docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md` using YAML + flow list.
-6. For complex UI flow-action specs, use `/screen-design-spec` to build/update `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`.
-7. Define:
-   - System components + data model
-   - API endpoints and flows
-   - Screen layouts
-   - Security/authz decisions
-8. Create/update:
-   - OpenAPI YAML + API endpoint markdown
-   - API flow list
-   - API design detail spec (when `orchestration.apiDesignDetailMode` is `auto/on`)
-   - Database spec (if DB impact exists)
-   - Flow-action spec and design layout (if UI impact exists)
-9. Ensure mapping UC/BR -> DB/API/screens and run output hygiene checks:
-   - EN artifacts use English narrative text (except clearly marked original-language appendix blocks)
-   - No mojibake/encoding corruption in markdown/yaml/txt outputs
-10. For benchmark runs, apply `governance/ai/core/SDTK_BENCHMARK_OQ_POLICY.md`: keep benchmark-expected open questions explicitly OPEN unless the requirement source resolves them.
-11. If anything is unclear, record OQ-xx in ARCH_DESIGN "Open Questions" and escalate to PM.
-12. Update shared state + Phase 3 checklist.
-13. Handoff: suggest user run `/dev` to implement the design.
+5. For API scope:
+   - generate or update YAML, endpoints markdown, and flow list
+   - if API detail is required, use `/api-design-spec`
+6. For UI scope:
+   - generate or update `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md`
+   - run `.claude/skills/design-layout/scripts/render_design_layout_images.py` to attempt screen preview rendering
+   - then generate or update `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md` using `/screen-design-spec`
+   - when no Figma or screenshot exists, use `generated-draft` with `DESIGN_LAYOUT` as the design source
+   - if rendering fails, use the render-skipped note instead of a broken image reference
+7. Define system components, data model, API endpoints, flows, screen layouts, and security decisions.
+8. Ensure mapping UC/BR to DB/API/screens and keep EN artifact hygiene.
+9. If anything is unclear, record OQ-xx in `ARCH_DESIGN` and escalate to PM.
+10. Update shared state and Phase 3 checklist.
+11. Handoff: suggest `/dev` after the design is complete.

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

@@ -1,25 +1,57 @@
 ---
 name: 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.
+description: Generate UI screen layout documentation for a feature, including PlantUML SALT wireframes and item tables. Use when a feature includes frontend or admin screens and you need docs/design deliverables.
 ---
 
 ## Required Inputs (read before proceeding)
 Read the following artifacts for the current feature:
-1. `docs/specs/BA_SPEC_*.md` — screens + fields
-2. `docs/api/[FEATURE_KEY]_ENDPOINTS.md` — API list
+1. `docs/specs/BA_SPEC_*.md` - screens and fields
+2. `docs/api/[FEATURE_KEY]_ENDPOINTS.md` - API list
 
 ## Input
 $ARGUMENTS
 
 # 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-*).
+   - 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 `.claude/skills/design-layout/scripts/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`.
+
+## Screen Image Renderer
+- Script: `.claude/skills/design-layout/scripts/render_design_layout_images.py`
+- Usage:
+  ```
+  python ".claude/skills/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`
+- Output: `.svg` files under `docs/specs/assets/<feature_snake>/screens/`
+- Failure policy: non-blocking. Warns and continues if rendering is unavailable.

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

@@ -1,19 +1,27 @@
 ---
 name: screen-design-spec
-description: Create/update screen flow-action specifications from requirement sources (Excel/Figma/spec docs), including screen flow PlantUML, UI item/action tables, API mapping tables, and screen-to-API traceability.
+description: Create or update screen flow-action specifications from requirement sources, including screen flow PlantUML, UI item tables, API mapping tables, and screen-to-API traceability.
 ---
 
 ## Required Inputs (read before proceeding)
 Read the following artifacts for the current feature:
-1. `docs/specs/BA_SPEC_*.md` — business rules, use cases
-2. `docs/architecture/ARCH_DESIGN_*.md` — system components
-3. `docs/api/[FEATURE_KEY]_ENDPOINTS.md` — API endpoints (when available)
+1. `docs/specs/BA_SPEC_*.md` - business rules and use cases
+2. `docs/architecture/ARCH_DESIGN_*.md` - system components
+3. `docs/api/[FEATURE_KEY]_ENDPOINTS.md` - API endpoints, when available
 
 ## Input
 $ARGUMENTS
 
 # 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:
@@ -24,29 +32,47 @@ $ARGUMENTS
 ## Required Inputs
 - Feature key/name
 - Primary requirement sources (BA spec, architecture, customer design docs)
-- Screen source references (Figma URLs and/or requirement screenshots)
+- Screen source references, using one of these design source modes:
+  - `source-backed`: Figma URLs and/or requirement screenshots
+  - `generated-draft`: generated layout from `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md`
 - API endpoint source (`docs/api/[FEATURE_KEY]_ENDPOINTS.md`) when available
 
 ## Process
 1. Read requirement sources and identify in-scope screens, dialogs, and transitions.
 2. Read and apply rules from `.claude/skills/references/FLOW_ACTION_SPEC_CREATION_RULES.md`.
-3. Build/update section `Feature overview` and `Screen flow action` (PlantUML).
-4. For each screen/dialog:
-   - Add metadata (screen ID, source link)
-   - Add screen image reference
+3. Determine design source mode per screen:
+   - If Figma URL or screenshot exists: use `source-backed`.
+   - If no Figma/screenshot but feature has UI scope: use `generated-draft` and reference the corresponding section in `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md`.
+   - If screen has no UI scope: use `none`.
+4. Build/update section `Feature overview` and `Screen flow action` (PlantUML).
+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)
-5. Build/update `System processing flow` from use-case and process sources.
-6. Build/update `Open questions` for unresolved behavior/API/data points.
-7. Build/update `Screen - API Mapping` summary section.
-8. Validate:
+6. Build/update `System processing flow` from use-case and process sources.
+7. Build/update `Open questions` for unresolved behavior/API/data points.
+8. Build/update `Screen - API Mapping` summary section.
+9. Validate:
    - global numbering consistency (no screen-level reset)
-   - no broken image paths
-   - PlantUML renderability
+   - no broken image paths (for `generated-draft` screens, verify `.svg` exists or use render-skipped note)
+   - 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
-9. Update document history and handoff to ARCH/DEV.
+   - 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 (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, replace the image reference with:
+      `> Screen image not rendered in this environment. See Design Source Reference for layout.`
+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: `.claude/skills/references/FLOW_ACTION_SPEC_CREATION_RULES.md`
@@ -55,14 +81,10 @@ $ARGUMENTS
 - Excel image export reference: `.claude/skills/references/excel-image-export.md`
 
 ## Validation Script
-- `scripts/validate_flow_action_spec_numbering.py`
-  - Checks duplicate/resetted numbering in action tables.
-  - Checks encoding/markdown hygiene.
-  - For EN artifacts, run with `--en-check`:
-    - `python scripts/validate_flow_action_spec_numbering.py --spec "docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md" --en-check`
-- `scripts/renumber_flow_action_spec_global.py`
-  - Auto-migrates action table `No` fields to global numbering.
+- `.claude/skills/screen-design-spec/scripts/validate_flow_action_spec_numbering.py`
+  - `python ".claude/skills/screen-design-spec/scripts/validate_flow_action_spec_numbering.py" --spec "docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md" --en-check`
+- `.claude/skills/screen-design-spec/scripts/renumber_flow_action_spec_global.py`
   - Dry-run:
-    - `python scripts/renumber_flow_action_spec_global.py --spec "docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md"`
+    - `python ".claude/skills/screen-design-spec/scripts/renumber_flow_action_spec_global.py" --spec "docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md"`
   - Apply:
-    - `python scripts/renumber_flow_action_spec_global.py --spec "docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md" --write`
+    - `python ".claude/skills/screen-design-spec/scripts/renumber_flow_action_spec_global.py" --spec "docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md" --write`

package/assets/toolkit/toolkit/templates/docs/api/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/templates/docs/api/API_DESIGN_DETAIL_TEMPLATE.md

@@ -16,6 +16,12 @@
 | ---: | --- | --- | --- |
 | 1 | TBD | TBD | `API_design.xlsx` |
 
+## Assumptions
+
+| # | Assumption | Verified | Risk if wrong |
+| ---: | --- | --- | --- |
+| 1 | TBD | No | TBD |
+
 ## 2. API Detail 1 - TBD
 
 **Endpoint:** `TBD`

package/assets/toolkit/toolkit/templates/docs/api/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/templates/docs/design/DESIGN_LAYOUT_TEMPLATE.md

@@ -28,10 +28,21 @@
 
 ## A-1. TBD
 
+> Generated outputs should use screen-local visual markers that reset per screen. Prefer Unicode circled-number markers in the real doc. The ASCII placeholders below keep this template PowerShell-safe, and `FLOW_ACTION_SPEC` will map the local markers to its global action-table numbers.
+
 ```plantuml
 @startsalt
 {
-  { "(1) TBD" | [(2) Action] }
+  {+
+    <b>Sample Screen</b>
+    ---
+    { "WF1 Keyword:" | "                " } | [ WF2 Search ]
+    ---
+    {#
+      <b>WF3 Name</b> | <b>WF4 Status</b>
+      Sample | Active
+    }
+  }
 }
 @endsalt
 ```

package/assets/toolkit/toolkit/templates/docs/specs/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/templates/docs/specs/FLOW_ACTION_SPEC_TEMPLATE.md

@@ -33,6 +33,12 @@
 ### 1.3 Implementation direction
 - TBD
 
+## Assumptions
+
+| # | Assumption | Verified | Risk if wrong |
+| ---: | --- | --- | --- |
+| 1 | TBD | No | TBD |
+
 ---
 
 ## 2) Screen flow action
@@ -41,16 +47,22 @@
 
 ```plantuml
 @startuml
-left to right direction
 skinparam shadowing false
-skinparam packageStyle rectangle
-
-rectangle "Screen A" as A
-rectangle "Screen B" as B
-rectangle "Dialog C" as C
-
-A --> B : action
-B --> C : open dialog
+skinparam activityBackgroundColor #FEFEFE
+skinparam activityBorderColor #333333
+
+title {{FEATURE_NAME}} - Screen Flow Action
+
+start
+partition "Main Flow" {
+  :SCR-01 Screen A;
+  note right
+    User reviews the main list and selects an action.
+  end note
+  -> Open detail;
+  :SCR-02 Screen B;
+}
+stop
 @enduml
 ```
 
@@ -76,11 +88,21 @@ Information:
 - Design Source Reference: Figma URL | screenshot path | `docs/design/DESIGN_LAYOUT_{{FEATURE_KEY}}.md` section reference | `N/A - no UI scope`
 
 Screen image:
+<!-- Use a file-relative markdown path from docs/specs/, not a project-root docs/specs/assets/... path. -->
 ![3.1 Screen A](assets/{{FEATURE_SNAKE}}/screens/scr_01.svg)
 
 <!-- If the .svg file does not exist (render unavailable), replace the image line above with: -->
 <!-- > Screen image not rendered in this environment. See Design Source Reference for layout. -->
 
+#### Wireframe Marker Mapping (Draft)
+
+> Generated-draft wireframe markers are screen-local visual references. Map each visible marker to the global action-table `No` used below.
+
+| No | Wireframe Marker | Action Table No | Item Name | Notes |
+| ---: | --- | ---: | --- | --- |
+| 1 | marker-1 | 1 | Item A | Visible on wireframe |
+| 2 | marker-2 | 2 | Item B | Visible on wireframe |
+
 | No | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note |
 | ---: | --- | --- | --- | --- | --- | --- | --- | --- | --- |
 | 1 | Item A | Button | - | - | - | - | Click | TBD | TBD |
@@ -103,11 +125,20 @@ Information:
 - Design Source Reference: Figma URL | screenshot path | `docs/design/DESIGN_LAYOUT_{{FEATURE_KEY}}.md` section reference | `N/A - no UI scope`
 
 Screen image:
+<!-- Use a file-relative markdown path from docs/specs/, not a project-root docs/specs/assets/... path. -->
 ![3.2 Screen B](assets/{{FEATURE_SNAKE}}/screens/scr_02.svg)
 
 <!-- If the .svg file does not exist (render unavailable), replace the image line above with: -->
 <!-- > Screen image not rendered in this environment. See Design Source Reference for layout. -->
 
+#### Wireframe Marker Mapping (Draft)
+
+> Generated-draft wireframe markers are screen-local visual references. Map each visible marker to the global action-table `No` used below.
+
+| No | Wireframe Marker | Action Table No | Item Name | Notes |
+| ---: | --- | ---: | --- | --- |
+| 1 | marker-1 | 3 | Item C | Visible on wireframe |
+
 | No | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note |
 | ---: | --- | --- | --- | --- | --- | --- | --- | --- | --- |
 | 3 | Item C | Toggle | boolean | flag_a | - | false | Toggle | TBD | TBD |

package/assets/toolkit/toolkit/templates/handoffs/ARCH_TO_DEV.md

@@ -0,0 +1,31 @@
+# ARCH to DEV Handoff
+
+## Required Inputs
+- `docs/architecture/ARCH_DESIGN_[FEATURE_KEY].md`
+- `docs/product/BACKLOG_[FEATURE_KEY].md`
+- when applicable:
+  - `docs/api/[FeaturePascal]_API.yaml`
+  - `docs/api/[FEATURE_KEY]_ENDPOINTS.md`
+  - `docs/database/DATABASE_SPEC_[FEATURE_KEY].md`
+  - `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md`
+  - `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`
+
+## Required Outputs
+- `docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md`
+- code and tests
+- Stage 1 and Stage 2 review evidence before QA handoff
+
+## Mandatory Checks
+- ARCH outputs are current and reference the same feature scope.
+- UI scope includes `DESIGN_LAYOUT` before `FLOW_ACTION_SPEC`.
+- API and DB source-of-truth files are available when implementation depends on them.
+
+## Forbidden Shortcuts
+- Do not start implementation before `FEATURE_IMPL_PLAN` is written and approved.
+- Do not treat architecture assumptions as verified facts without citing the source.
+
+## Handoff Message Shape
+- Feature: `[FEATURE_KEY]`
+- Required implementation slice: file or module scope
+- Required proving checks: test or lint or build commands
+- Upstream blockers or assumptions: explicit list