sdtk-kit 0.3.8 → 1.0.0

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

@@ -1,468 +0,0 @@
-# API DESIGN + FLOWCHART CREATION RULES FINAL
-
-This file is the canonical rule set for:
-- API flow source (`*_api_flow_list.txt`)
-- PlantUML API flowcharts
-- API design detail markdown (`*_API_DESIGN_DETAIL.md`)
-
-Use `YAML_CREATION_RULES_FINAL.md` as the source of truth for endpoint contract design.
-
-The rules below include the 2026-03-03 flow-style refinements extracted from the Whiteboard API flowchart review.
-
-## 1. Final Review Result
-
-After the final pass on `docs/api/schedule_whiteboard_api_flow_list.txt`, there are no remaining critical style mismatches that should block reuse of the current flowchart-writing rules.
-
-Current state:
-- All API blocks use visible API header lines.
-- Search-like APIs use query-builder style.
-- CRUD/detail APIs no longer overuse search-style `fullQuery` construction.
-- Batch create uses batch-create style instead of search-style query-builder.
-- `api_design_detail.md` has been regenerated and is aligned with the current flow source.
-
-Accepted low-priority exceptions:
-- `POST /file-manager/env/{company_uuid}` uses pseudo `UPSERT` wording. This is acceptable because it is a shared upsert-style API, not a search API.
-- `GET /api/whiteboard/assignment/{company_uuid}/{sagyo_assign_uuid}` still uses a fixed `query = ...` + `LEFT JOIN ...` style. This is intentional and acceptable for a fixed-detail API.
-
-## 2. Source of Extracted Rules
-
-These rules were extracted by comparing:
-- `docs/api/schedule_whiteboard_api_flow_list.txt`
-- `docs/api/api_design_detail.md`
-- `Example/Docs/API/bukken-api-flowchart-list.txt`
-
-Primary sample references:
-- `POST /bukken/{company_uuid}` style
-- `POST /bukken/edit/{company_uuid}/{bukken_uuid}` style
-- `POST /bukken/delete-parmanent/{company_uuid}/{bukken_uuid}` style
-- `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
-
-Every API block must start with a visible API header line, for example:
-
-```text
-API: <METHOD> <PATH>  <Short Title>
-```
-
-Project-specific variants such as `笆API:` are acceptable only when encoding is stable.
-
-Reason:
-- Matches the sample style.
-- Makes raw flow-list files scannable before rendering.
-- Reduces ambiguity when one file contains many APIs.
-
-### Rule B. Use one `@startuml` block per API when generator mapping depends on block count
-
-If the markdown/API-design generator maps flow blocks to API endpoints by block count/order:
-- keep exactly one main `@startuml ... @enduml` block per API
-- do not split helper flows into extra standalone blocks unless the generator is updated accordingly
-
-Reason:
-- Avoids breaking flow-to-endpoint mapping in generated `*_API_DESIGN_DETAIL.md`.
-
-### Rule C. Flow style must match API type
-
-Do not use one style for every API.
-Choose the flow style based on the API purpose:
-
-1. Search/List/Lookup APIs
-- Use query-builder style.
-
-2. Create APIs
-- Use CRUD create style.
-
-3. Edit APIs
-- Use CRUD update style.
-
-4. Delete APIs
-- Use CRUD delete style.
-
-5. Detail APIs
-- Use fixed-record read style.
-
-6. Batch create APIs
-- Use batch-create style with loop.
-
-Reason:
-- This is the main difference between the sample Bukken flowchart style and the over-generalized Whiteboard draft.
-
-## 4. Search / List API Rules
-
-Applies to:
-- assignment search APIs
-- reserve employee/customer-employee search APIs
-- duplicate-check / lookup APIs that are effectively query-based
-- shared env lookup APIs when they dynamically build lookup conditions
-
-### Rule D. Search APIs should use query-builder style
-
-Preferred structure:
-
-```text
-:Create search query and condition statement from request.data.info;
-:query = "SELECT ... FROM ...";
-:query += " LEFT JOIN ...";
-:condition = "WHERE ...";
-...
-:order_by = "ORDER BY ...";
-:Compose full query:\nfullQuery = query + " " + condition;
-:Add order_by into fullQuery;
-:Execute fullQuery and get data;
-:Close DB connection;
-:Create api response;
-```
-
-### Rule E. Use uppercase table/column names inside pseudo-SQL
-
-Inside SQL-like action text:
-- use uppercase table names
-- use uppercase column names where practical
-
-Good:
-- `CLD_DAT_BUKKEN_INFO`
-- `CLD_DAT_BUKKEN_SAGYO_ASSIGN_INFO`
-
-Avoid:
-- lowercase-only SQL object names in pseudo-SQL lines
-
-Reason:
-- Matches the sample style and improves visual separation between logic text and table identifiers.
-
-### Rule E-1. Do not use fake helper-function wording unless a helper flow is defined
-
-Do not write:
-- `Call search_logic_function(parameters)`
-- `Execute search_logic_function(parameters)`
-
-unless the flow source also contains a real helper sub-flow block that defines that function logic.
-
-If the helper is not actually defined in the same source:
-- write the processing step directly inline
-
-Good:
-- `Create search query and condition statement from request.data.info;`
-- `Create duplicate check query and condition statement from request.data.info;`
-
-Reason:
-- Avoids implying a reusable sub-flow that does not exist.
-- Keeps the flow self-contained and accurate.
-
-### Rule F. Dynamic array filters should use object-based wording
-
-For array filters, use the sample-like loop style:
-
-```text
-if (data.info.department_uuids not null && data.info.department_uuids not empty) then (yes)
-  :condition += " AND ( 1 != 1 ";
-  repeat
-    :Get departmentObject from data.info.department_uuids;
-    :condition += " OR E.DEPARTMENT_UUID = <departmentObject.uuid>";
-  repeat while (more value data?) is (yes)
-  ->no;
-  :condition += " )";
-else (no)
-endif
-```
-
-Do not use overly simplified wording like:
-- `Add department filter`
-
-Reason:
-- The sample explicitly shows how OR-group conditions are built.
-
-### Rule G. Search APIs should not describe response shaping internals
-
-Avoid lines such as:
-- `Compute duplicate_assign ...`
-- `Group data into ...`
-- `Return data.xxx[]`
-- `Aggregate created_count ...` (for non-batch search flows)
-
-Instead end the flow at:
-- query completed
-- DB connection closed
-- API response created
-
-Reason:
-- The response structure is already defined in YAML.
-- Flowchart should focus on processing logic, not renderer-side or response-object assembly internals.
-
-### Rule H. Explicit `ORDER BY` is required when output order matters
-
-If the endpoint contract depends on a specific order:
-- define `order_by = "ORDER BY ..."`
-- then add it into `fullQuery`
-
-Do not leave ordering implicit.
-
-## 5. Create API Rules
-
-Applies to:
-- single create APIs
-
-### Rule I. Create APIs should use `Insert into ... with parameter value`
-
-Preferred style:
-
-```text
-:Insert into CLD_DAT_XXX with parameter value
-field_a = param.data.info.field_a
-field_b = param.data.info.field_b
-create_dt = now;
-:GET inserted_xxx_uuid = XXX_UUID value when Insert into CLD_DAT_XXX;
-:Close DB connection;
-:Create api response;
-```
-
-### Rule J. Do not over-describe query-builder logic inside create flows
-
-Avoid using:
-- `query = "SELECT 1 ..."`
-- `condition = ...`
-- `Compose full query ...`
-
-inside normal create flows.
-
-If duplicate/business validation is needed:
-- describe it as a business step only
-
-Example:
-- `Check overlap conflicts with current parameter value;`
-
-Reason:
-- This matches the sample create style and keeps flow readable.
-
-## 6. Edit API Rules
-
-Applies to:
-- update APIs
-
-### Rule K. Edit APIs should follow `Select existing -> Update with parameter value`
-
-Preferred structure:
-
-```text
-:Get target_uuid from endpoint;
-:Select from CLD_DAT_XXX with target_uuid and del_flg = 0;
-if (record exists) then (yes)
-else (no)
-  :Return error status = 140 ...;
-  stop
-endif
-:Check business rule if needed;
-:Update CLD_DAT_XXX with parameter value
-field_a = param.data.info.field_a
-field_b = param.data.info.field_b
-update_dt = now
-where target_uuid = target_uuid;
-:Close DB connection;
-:Create api response;
-```
-
-### Rule L. Keep business checks short inside edit flows
-
-If edit has duplicate overlap or other business validation:
-- keep it as one business step
-- do not expand it into a full search-style query-builder
-
-Good:
-- `Check overlap conflicts excluding current xxx_uuid;`
-
-Avoid:
-- full `query/condition/fullQuery` sequence inside edit flow
-
-## 7. Delete API Rules
-
-Applies to:
-- logical delete
-- physical delete
-
-### Rule M. Delete APIs should follow `Select existing -> Delete/Update -> Close -> Response`
-
-Preferred structure:
-
-```text
-:Get target_uuid from endpoint;
-:Select from CLD_DAT_XXX with target_uuid and del_flg = 0;
-if (record exists) then (yes)
-else (no)
-  :Return error status = 140 ...;
-  stop
-endif
-:Update CLD_DAT_XXX with parameter value
-del_flg = 1,
-update_dt = now
-where target_uuid = target_uuid;
-:Close DB connection;
-:Create api response;
-```
-
-If the API is truly permanent delete:
-- use `Delete ... with key is ...`
-
-Rule:
-- style may mirror permanent-delete sample
-- but business semantics must still match the actual API contract
-
-## 8. Detail API Rules
-
-Applies to:
-- read-one / detail APIs
-
-### Rule N. Detail APIs may use a fixed query, but not search-style dynamic query-builder
-
-Allowed:
-
-```text
-:Get target_uuid from endpoint;
-:query = "SELECT ... FROM CLD_DAT_XXX WHERE TARGET_UUID = target_uuid";
-:query += " LEFT JOIN ...";
-:Execute query and get data;
-if (record exists) then (yes)
-...
-:Close DB connection;
-:Create api response;
-```
-
-Avoid:
-- `condition = ...`
-- `Compose full query ...`
-- dynamic filter loops
-
-Reason:
-- Detail APIs are fixed-record lookups, not flexible searches.
-
-## 9. Batch Create API Rules
-
-Applies to:
-- APIs that create multiple records in one request
-
-### Rule O. Batch create APIs should use create-style logic with a loop
-
-Preferred structure:
-
-```text
-:Create target date list ...;
-...
-repeat
-  :Build per-item datetime/value;
-  :Check business conflict with current target date parameter value;
-  if (duplicate and skip = false) then (yes)
-    :Append skipped result ...;
-  else (no)
-    :Insert into CLD_DAT_XXX with parameter value
-    ...
-    :GET inserted_xxx_uuid = XXX_UUID value when Insert into CLD_DAT_XXX;
-    :Append created result ...;
-  endif
-repeat while (has next target item?) is (yes)
-:Build batch result list and summary counts;
-:Close DB connection;
-:Create api response;
-```
-
-### Rule P. Do not use search-style query-builder in batch-create loops
-
-Avoid inside the loop:
-- `query = "SELECT 1 ..."`
-- `condition = ...`
-- `Compose full query ...`
-
-Even when duplicate validation exists, batch create should still read like a create flow with looped business validation.
-
-## 10. Shared System API Rules
-
-Applies to:
-- APIs reused from another module but documented in feature flowchart
-
-### Rule Q. Shared lookup APIs may still use query-builder style if they behave like lookup/search
-
-Example:
-- environment lookup APIs that build conditions from request array items
-
-Allowed:
-- `query = ...`
-- `condition = ...`
-- `Compose full query ...`
-
-### Rule R. Shared upsert APIs should use action-oriented wording, not search wording
-
-Example:
-
-```text
-:Create Environment Manager upsert statement from request.data;
-:query = "UPSERT CLD_DAT_ENV_INFO";
-:Resolve target row by ...;
-:Set VALUE / NUMVALUE ...;
-:Execute upsert statement;
-:Close DB connection;
-:Create api response;
-```
-
-Reason:
-- Keeps style aligned with operation type.
-
-## 11. Error / Connection / Ending Rules
-
-### Rule S. Keep auth and validation at the top
-
-Use the common pattern:
-- authentication
-- permission
-- validation
-- business processing
-- DB close
-- response
-
-### Rule T. `Close DB connection;` should be near the end of the main flow
-
-Preferred:
-- after DB processing finishes
-- before `Create api response;`
-
-Avoid:
-- excessive `Close DB connection;` inside every inner loop branch unless the logic truly requires separate connections
-
-### Rule U. End with `Create api response;`
-
-Use a simple terminal response action.
-
-Do not over-specify:
-- HTTP 200
-- response JSON object construction
-- field-by-field response shaping
-
-unless there is a concrete reason the sample style requires it.
-
-## 12. Non-Flow Logic That Should Stay Out of the Flowchart
-
-Do not put these into the flow unless they are the core processing logic:
-- FE-only rendering logic
-- detailed response nesting assembly
-- UI display-specific transformations already described by YAML schema
-
-Reason:
-- Flowchart should describe processing logic.
-- YAML and endpoint docs already define the response contract.
-

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

@@ -1,20 +0,0 @@
-# FLOWCHART CREATION RULES (Compatibility Note)
-
-This file is kept only for backward compatibility.
-
-Do not use this file as the primary source of truth anymore.
-The rule set has been split into two files:
-- `YAML_CREATION_RULES_FINAL.md` (root) / `templates/docs/api/YAML_CREATION_RULES.md` (toolkit)
-- `API_DESIGN_FLOWCHART_CREATION_RULES_FINAL.md` (root) / `templates/docs/api/API_DESIGN_FLOWCHART_CREATION_RULES.md` (toolkit)
-
-Use the YAML rules file for:
-- endpoint path/method conventions
-- request/response schema design
-- contract-level API rules
-
-Use the API design + flowchart rules file for:
-- flow list writing
-- PlantUML flow depth and wording
-- API design detail markdown rules
-
-This compatibility note should remain only until all references are migrated.

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

@@ -1,83 +0,0 @@
----
-name: sdtk-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.
----
-
-# 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:
-  - `docs/api/[FeaturePascal]_API.yaml`
-  - `docs/api/[FEATURE_KEY]_ENDPOINTS.md`
-  - `docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md`
-  - `docs/api/[feature_snake]_api_flow_list.txt`
-  - `docs/database/DATABASE_SPEC_[FEATURE_KEY].md`
-  - `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md`
-  - `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`
-
-## Flow Overview
-
-```dot
-digraph sdtk_arch_flow {
-  rankdir=TB;
-  BA_SPEC -> ARCH_DESIGN;
-  ARCH_DESIGN -> DESIGN_LAYOUT;
-  DESIGN_LAYOUT -> FLOW_ACTION_SPEC;
-  ARCH_DESIGN -> API_YAML;
-  API_YAML -> API_DETAIL;
-}
-```
-
-## 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:
-   - `./references/YAML_CREATION_RULES.md`
-   - `./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 `./references/FLOW_ACTION_SPEC_CREATION_RULES.md`.
-5. If API detail spec is required, use `sdtk-api-design-spec` to build/update `docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md` using YAML + flow list.
-6. For UI-scope features, enforce this generation sequence:
-   a. Generate/update `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md` first (using `sdtk-design-layout`).
-   b. Attempt to render screen preview images from the layout using `render_design_layout_images.py`. Output: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`. If rendering fails (no Java/plantuml.jar), fall back to the render-skipped note -- do not silently skip.
-   c. Then generate/update `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md` (using `sdtk-screen-design-spec`).
-   d. The flow-action spec must reference the design-layout doc as its design source when no Figma/screenshot is available (Design Source Type: `generated-draft`). Use rendered `.svg` files as the screen image. If render failed, use the render-skipped note instead of a broken image reference.
-7. For complex UI flow-action specs, use `sdtk-screen-design-spec` to build/update `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`.
-8. Define:
-   - System components + data model
-   - API endpoints and flows
-   - Screen layouts
-   - Security/authz decisions
-9. 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)
-   - Design layout (if UI impact exists) - must be created before flow-action spec
-   - Flow-action spec (if UI impact exists) - must reference design layout as fallback source
-10. 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
-11. 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.
-12. If anything is unclear, record OQ-xx in ARCH_DESIGN "Open Questions" and escalate to `@pm` for a decision.
-13. Update shared state + Phase 3 checklist.
-14. Handoff: `@dev please implement ...`.
-
-## Order-Critical Hard Gate
-For UI-scope features, do not generate or update `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md` until `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md` already exists and is current enough to serve as the design source for the same scope.
-
-If the layout is missing, stale, or cannot support the flow-action spec, stop and fix the layout first. Do not reverse the order and repair it later.
-
-
-## Common Mistakes
-
-| Mistake | Why it is wrong | Do instead |
-|---|---|---|
-| Generate `FLOW_ACTION_SPEC` before `DESIGN_LAYOUT` for UI scope | Forces the spec to invent screen behavior without a design source | Create or refresh the layout first, then derive the flow-action spec |
-| Treat API YAML, API detail, and flow-action outputs as independent documents | Causes naming and traceability drift across artifacts | Keep ARCH outputs linked through shared requirements and path policy |
-| Close open questions silently during ARCH | Hides unresolved design decisions from downstream roles | Record `OQ-xx` explicitly and escalate through `@pm` |