sdtk-kit 0.3.0

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

@@ -0,0 +1,397 @@
+# Flowchart Creation Rules for AI Agents (PlantUML)
+
+This document defines reusable rules for creating and updating API flowcharts in this project.
+Target files are usually API flow list documents (for example `*_api.txt`) and API YAML files (for example `docs/api/*.yaml`).
+
+## 1. Scope and Goal
+
+- Use PlantUML activity diagrams for API process flows.
+- Keep diagrams readable, implementation-aware, and consistent with current backend logic.
+- Prefer minimal-impact documentation changes when existing customer logic is already running.
+
+## 2. File and Diagram Structure
+
+- One API flow = one `@startuml ... @enduml` block.
+- If helper logic is extracted, add a separate `@startuml ... @enduml` block for that helper.
+- Keep API title in `partition`:
+  - `partition "POST  **/api/path/{company_uuid}**  Japanese summary" { ... }`
+- Optional helper flow style:
+  - `rectangle "Logic function name" { ... }`
+
+## 3. Mandatory Activity Syntax Rules
+
+- Every action line must end with `;`
+- Every `if (...) then (...)` must be closed by `endif`
+- Use `else (no)` and `then (yes)` labels explicitly for branch readability.
+- Use `repeat ... repeat while ...` only when loop behavior is required.
+
+## 4. Color/Highlight Rules (Non-deprecated)
+
+Use stereotype-based color syntax (new style), not old prefix style.
+
+- Correct:
+  - `:Return Error status = 100: Parameter invalid;<<#pink>>`
+  - `:Call query_search_by_keyword() function;<<#lightGreen>>`
+- Avoid deprecated old style:
+  - `#pink:...`
+  - `#lightGreen:...`
+
+## 5. Standard API Flow Skeleton
+
+```plantuml
+@startuml
+partition "POST  **/sample/path/{company_uuid}**  API summary" {
+  start
+  :Process authentication\\nCommon auth process;
+  :Validate parameter;
+  if (is valid) then (no)
+    :Return Error status = 100: Parameter invalid;<<#pink>>
+    stop
+  else (yes)
+  endif
+  :Main process;
+  :Close DB connection;
+  :Create api response;
+  stop
+}
+@enduml
+```
+
+## 6. Query-Building Style Rules
+
+When describing SQL-like logic in flowchart:
+
+- Build query in steps:
+  1. `Create search query and condition statement from request.data;`
+  2. `query = "...";`
+  3. `condition = "...";`
+  4. optional condition append blocks
+  5. `Compose full query: fullQuery = query + condition;`
+  6. apply order/paging
+  7. execute query
+
+- Keyword pattern:
+  - `LIKE '%data.info.keyword%'`
+- Order pattern:
+  - `Add order by data.info.order_flg data.info.order_type into fullQuery;`
+- Paging pattern:
+  - `Add "LIMIT = data.info.limit OFFSET = data.info.offset" into fullQuery;`
+
+### 6.1 Endpoint-level Mapping Must Be Explicit
+
+For keyword/order enhancements, always document mapping between request params and DB columns per endpoint.
+
+- `keyword` must list all searchable columns/tables.
+- `order_flg` must list allowed sort targets and mapped columns.
+- `order_type` must be documented as `asc/desc`.
+- If payload includes new fields that are not handled by current legacy code,
+  add explicit processing logic for those new fields in the helper flow.
+  Do not silently ignore newly introduced request fields.
+
+Example (`/bukken-manager/regno/customer/search/{company_uuid}`):
+- `keyword`:
+  - `CLD_DAT_CUSTOMER_REG_NO_INFO.customer_reg_no`
+  - `CLD_MST_LOCATION_INFO.location_name`
+  - `CLD_MST_REG_NO_TYPE_INFO.name`
+- `order_flg`:
+  - `customer_reg_no` / `location_name` / `name`
+- `order_type`:
+  - `asc` / `desc`
+
+## 7. Backward-Compatible Merge Pattern
+
+When new requirements are added to an existing API:
+
+- Keep current handler path for old request behavior.
+- Add conditional branch for new logic only when required params exist.
+- Recommended branch style:
+  - If all new params are null -> keep old logic
+  - Else -> call extracted helper function
+- Use this exact "no-impact first" branch when preserving customer legacy handlers:
+  - `if (data.info.keyword null and data.info.order_flg null and data.info.order_type null) then (yes)`
+  - `:Keep the current search logic handler: <existing_handler>();`
+  - `else (no)` -> call helper for new query logic
+- In the legacy branch, do not duplicate old internal sub-steps unless explicitly requested.
+  - Avoid extra lines like mapping/query detail when they are already part of existing handler behavior.
+  - Prefer one concise line:
+    - `:Keep the current search logic handler: <existing_handler>();`
+
+Example:
+
+```plantuml
+if (data.info.keyword null and data.info.order_flg null and data.info.order_type null) then (yes)
+  :Keep the current search logic handler: regno_search();
+else (no)
+  :Call query_search_by_keyword() function;<<#lightGreen>>
+endif
+```
+
+## 8. Helper Function Diagram Pattern
+
+```plantuml
+@startuml
+rectangle "Logic query search by keyword" {
+  :query_search_by_keyword();<<#lightGreen>>
+  :Create search query and condition statement from request.data;
+  :query = "...";
+  :condition = "...";
+  if (data.info.keyword not null) then (yes)
+    :condition += "...";
+  else (no)
+  endif
+  :Compose full query:\\nfullQuery = query + condition;
+  :Add order by data.info.order_flg data.info.order_type into fullQuery;
+  :Add "LIMIT = data.info.limit OFFSET = data.info.offset" into fullQuery;
+  :Execute fullQuery and get data;
+  :return return_datas;
+}
+@enduml
+```
+
+### 8.1 Helper Naming Rule
+
+- Use helper names that include endpoint domain to avoid collisions across many APIs.
+- Recommended:
+  - `query_search_by_keyword()` for generic case
+  - `query_search_by_keyword_customer_regno()` for customer-regno endpoint
+
+### 8.2 Legacy Fallback Rule (Search APIs)
+
+- When modernizing an existing search endpoint, explicitly describe legacy fallback behavior:
+  - soft-delete flag fallback from existing code path (if any)
+  - default order fallback when `order_flg/order_type` is absent
+  - default filters applied when optional inputs are null
+- Keep these fallback notes visible in flowchart text to avoid behavior drift.
+
+### 8.3 Extended Filter Branch/Response Rule
+
+- If new optional filter fields are added, include all of them in the no-impact branch check.
+- When relation-based filters are used, explicitly show join/filter logic in helper flow.
+- If response contains multiple typed lists, keep each list explicit in flowchart/YAML (for example `data.<entity>_info[]`) and include summary metadata such as `count` when applicable.
+
+## 9. Path Canonicalization Rule
+
+- If YAML path and actual route path are different, use the confirmed actual route path in flowchart.
+- Always prioritize route path defined in backend code (`urls.py`) over YAML documentation.
+- If route path cannot be found in code, fallback to YAML path and mark it as assumed/temporary.
+- Always confirm this with user before finalizing.
+
+## 9A. API Endpoint Design Rules (Project Standard)
+
+These rules must be applied when creating/updating API flowcharts and YAML in this project.
+
+- Use singular object keyword in endpoint path:
+  - Correct: `/invoice`, `/assignment`, `/personal-schedule`
+  - Avoid: `/invoices`, `/assignments`
+- Use canonical business-domain keywords from glossary/spec terminology.
+- Avoid ambiguous aliases when official domain terms exist.
+- Use action keywords that describe behavior clearly:
+  - List: `.../list/...`
+  - Update: `.../edit/...`
+  - Delete: `.../delete/...`
+  - Multi-create: `.../multi-create`
+  - Avoid vague action keyword `bulk` when behavior is multi-create.
+
+### 9A.1 Endpoint Pattern
+
+- List API:
+  - `GET /{object}/list/{company_uuid}/{bukken_uuid}`
+- Create API:
+  - `POST /{object}/{company_uuid}/{bukken_uuid}`
+- Edit API:
+  - `POST /{object}/edit/{company_uuid}/{object_uuid}`
+- Detail API:
+  - `GET /{object}/edit/{company_uuid}/{object_uuid}`
+- Delete API:
+  - `POST /{object}/delete/{company_uuid}/{object_uuid}`
+
+### 9A.2 HTTP Method Policy
+
+- Do not use `PUT` for update APIs. Use `POST .../edit/{uuid}`.
+- Do not use `DELETE` method for delete APIs. Use `POST .../delete/{uuid}`.
+
+### 9A.3 Canonical Examples
+
+- Invoice sample:
+  - `GET /invoice/list/{company_uuid}/{bukken_uuid}`
+  - `POST /invoice/{company_uuid}/{bukken_uuid}`
+  - `POST /invoice/edit/{company_uuid}/{invoice_uuid}`
+  - `GET /invoice/edit/{company_uuid}/{invoice_uuid}`
+  - `POST /invoice/delete/{company_uuid}/{bukken_uuid}`
+
+## 9B. General Design and Documentation Governance Rules
+
+Apply the rules below as cross-project standards for API YAML and flowchart generation.
+These rules complement section `9A` (path syntax + method policy) and avoid redefining it.
+
+### 9B.1 Rule Precedence and Consistency
+
+- Endpoint naming/method conventions must follow section `9A`.
+- If a feature needs an exception from `9A`, document the reason and get explicit confirmation before finalizing.
+- Keep terminology consistent across path, request/response schema, flowchart labels, and API summary tables.
+
+### 9B.2 Parameter Placement Rule
+
+- Path parameters: identity and routing keys (`{company_uuid}`, `{resource_uuid}`).
+- Query parameters: lightweight filtering/sorting/paging.
+- Request body: complex/multi-field search criteria.
+- If retrieval requires many filter fields, prefer dedicated `POST .../search` over overloaded query strings.
+
+### 9B.3 Read Contract Shape Rule (List vs Search)
+
+- Use list-style read API for simple retrieval contracts.
+- Use search-style read API when filter logic is complex or payload-based.
+- If one endpoint forces heavy client-side matching/filtering for different screen modes, split read endpoints by view purpose.
+
+### 9B.4 Endpoint Split vs Merge Decision Rule
+
+- Split endpoints when:
+  - view/use-case shaping is materially different
+  - one endpoint causes excessive client orchestration
+- Merge endpoints/datasets when:
+  - data is always consumed together under the same filter context
+  - separate endpoints only add latency and maintenance cost
+- Record split/merge rationale in API description and flowchart notes.
+
+### 9B.5 Reuse vs New Endpoint Rule
+
+- Reuse existing endpoints only when request/response contract is truly compatible with target screen logic.
+- If existing API is semantically close but contract-incompatible, create a bounded new endpoint for that use case.
+- Mark endpoint lifecycle in docs via `API Type` classification (see `9B.8`).
+
+### 9B.6 Namespace and Path Redundancy Rule
+
+- Separate namespaces by bounded context/domain.
+- Avoid repeating parent namespace meaning in child path segments.
+- Keep paths concise but semantically clear.
+
+### 9B.7 Screen-to-API Traceability Rule
+
+- Every UI flow/action section must map:
+  - trigger/action
+  - called API
+  - response fields used for rendering
+- Explicitly mark when a single endpoint serves multiple actions (initial load, search, refresh, etc.).
+
+### 9B.8 API List Governance Rule (Markdown Specs)
+
+- API summary tables must include at least:
+  - `No`
+  - `Method`
+  - `Endpoint`
+  - `API Type`
+  - `Description`
+- Group APIs by delivery status for planning visibility:
+  1. `New`
+  2. `Deferred`
+  3. `Existing (reuse)`
+- After regrouping, renumber `No` sequentially.
+
+### 9B.9 Change Management Rule
+
+- For every endpoint rename/add/remove/merge:
+  - update endpoint detail sections
+  - update API summary tables
+  - update screen-to-API mapping
+  - append a new row in document history
+- Preserve old history rows; never rewrite historical entries.
+
+### 9B.10 Canonical Response Envelope Rule
+
+- Use one canonical response envelope across a bounded module/feature.
+- Keep the envelope shape consistent in YAML examples, flowchart return nodes, and markdown endpoint tables.
+- Recommended normalized envelope keys:
+  - `status`
+  - `msg`
+  - `data`
+  - `format_version`
+- If a legacy API has a different wrapper, document it explicitly as an exception.
+
+### 9B.11 Business Status Rule
+
+- Business execution result must be represented in response body `status` (not only by HTTP code).
+- Flowchart branches must map to business status outcomes, including validation and duplicate/conflict-like results.
+- Document endpoint-level status code matrix in API docs when branching is non-trivial.
+- HTTP status policy can vary by system profile, but body `status` must remain deterministic.
+
+### 9B.12 Request Body Wrapper Rule
+
+- For write/search APIs that use POST payloads, prefer a stable top-level wrapper object:
+  - `data: { ... }`
+- Keep filter/search fields under `data` when criteria are complex or nested.
+- If legacy contracts do not use wrapper objects, document exception and compatibility reason.
+
+### 9B.13 Traceability Metadata Rule
+
+- YAML should include explicit traceability metadata for each endpoint (for example `x-traceability`).
+- Minimum mapping targets:
+  - BR (business rule)
+  - UC (use case)
+  - AC (acceptance criteria)
+- Flow list and markdown API docs should preserve the same mapping IDs to keep cross-artifact traceability.
+
+### 9B.14 Language and Encoding Governance
+
+- EN artifact set must use English narrative consistently.
+- Save generated markdown/YAML as UTF-8 and remove mojibake/corrupted characters before handoff.
+- If source input is VI/JP, keep original text only in dedicated appendix/quotation blocks when needed for traceability.
+
+### 9B.15 Abbreviations and Table Numbering Governance
+
+- For generated markdown specs, include an `Abbreviations` section near the top when acronyms are used.
+- Apply `No` column and sequential renumbering policy by following section `9B.8`.
+
+## 9C. Project Profile Overlay Rule (Cross-Project Reuse)
+
+- Separate reusable core rules from system-specific constraints.
+- Keep system-specific choices in a project profile layer, for example:
+  - fixed HTTP policy patterns
+  - datetime timezone/local-naive policy
+  - method conventions such as POST-based edit/delete
+- When reusing these rules for a new system, adopt core rules first, then explicitly decide profile overrides.
+- Do not silently promote one system profile as global default for all projects.
+
+## 10. Wording Rules
+
+- Use concrete action verbs:
+  - `Select ...`
+  - `Update ...`
+  - `Insert ...`
+  - `Create api response;`
+- For existing behavior preservation, use explicit wording:
+  - `Keep the current search logic handler: <function>();`
+- Do not add redundant response details if globally standardized.
+  - Prefer `:Create api response;` over verbose wrappers.
+
+## 11. Error/Status Rules in Flow Text
+
+- Parameter validation error: usually `status = 100` (unless API-specific rule says otherwise).
+- Temporary unknown error code policy may use `status = 900` if already agreed.
+- Keep status usage consistent with confirmed project decisions.
+
+## 12. Common Preview Errors and Fixes
+
+- Error: `Cannot find group ... @enduml`
+  - Cause: missing `endif` or malformed action statement
+  - Fix: close all branches and ensure each action line ends with `;`
+
+- Warning: `This syntax is deprecated...`
+  - Cause: old color syntax (`#pink:...`, `#lightGreen:...`)
+  - Fix: move color marker to end of action:
+    - `:...;<<#pink>>`
+    - `:...;<<#lightGreen>>`
+
+## 13. Final Checklist Before Handoff
+
+- Diagram renders in PlantUML Preview without error.
+- No deprecated color syntax warnings.
+- All `if` blocks have matching `endif`.
+- New logic branch does not remove old logic path unless explicitly requested.
+- SQL condition/order/paging statements match agreed spec.
+- API path and method match the confirmed actual route (use YAML path only when they are identical).
+- Response envelope is consistent with module-level canonical contract.
+- Business `status` mapping is explicit in both YAML and flow branches.
+- POST search/write payload wrapper (`data`) is consistent (or exception documented).
+- Traceability links (BR/UC/AC) are present and consistent across artifacts.
+- EN/UTF-8 quality check passed (no mixed-language drift, no mojibake).
+

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

@@ -0,0 +1,43 @@
+---
+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)
+
+## 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`
+
+## Process
+1. Read BA spec + 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 rules from `./references/FLOWCHART_CREATION_RULES.md` before defining endpoints/flows.
+4. If architecture output includes screen flow-action specs, read and apply rules from `./references/FLOW_ACTION_SPEC_CREATION_RULES.md` (global numbering policy).
+5. If API detail spec is required, use skill `sdtk-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 skill `sdtk-screen-design-spec` to build/update `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`.
+7. Define:
+   - System components + data model
+   - API endpoints and flows (if backend changes)
+   - Screen layouts (if UI changes)
+   - 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. If anything is unclear: record OQ-xx in ARCH_DESIGN "Open Questions" and escalate to `@pm` for a decision (PM asks the user if still missing info).
+11. Update shared state + Phase 3 checklist.
+12. Handoff: `@dev please implement ...`.
+

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

@@ -0,0 +1,212 @@
+# API Design Creation Rules for AI Agents (Excel Template)
+
+This document defines reusable rules for creating API design documents in Excel format based on `Example/Docs/API/API_design.xlsx`.
+
+## 1. Scope and Goal
+
+- Reuse one consistent Excel structure for API contract documentation.
+- Keep flow, endpoint parameters, request schema, response schema, and revision history in one workbook.
+- Keep generated sheets deterministic and review-friendly.
+
+## 2. Source Template Baseline
+
+| No | Sheet Pattern | Purpose |
+| ---: | --- | --- |
+| 1 | `History` | Global workbook change history |
+| 2 | `API detail (...)` | One API per sheet |
+
+Observed baseline in `API_design.xlsx`:
+- 1 history sheet.
+- 5 API detail sheets (list/create/detail/update/logical delete).
+
+## 3. Workbook Rules
+
+### 3.1 Sheet Naming
+
+- Use one API per sheet.
+- Recommended naming style:
+  - `API detail (<domain action>)`
+- Keep API sheet order stable (for example: list -> create -> detail -> update -> delete).
+
+### 3.2 History Sheet
+
+- Keep `History` as the first sheet.
+- Header layout:
+  - `A3=Date`
+  - `C3=Version`
+  - `F3=Editor`
+  - `M3=Edit content`
+- Append rows only. Do not rewrite historical rows.
+
+## 4. API Detail Sheet Layout
+
+### 4.1 Header Metadata Block
+
+Use this label/value map:
+
+| No | Label Cell Group | Value Cell Group | Meaning |
+| ---: | --- | --- | --- |
+| 1 | `Q1:X1` | `Y1:AQ1` | System name |
+| 2 | `Q2:X2` | `Y2:AQ2` | System ID |
+| 3 | `Q3:X3` | `Y3:AQ3` | Subsystem name |
+| 4 | `Q4:X4` | `Y4:AQ4` | Function name |
+| 5 | `AR1:AV1` | `AW1:BC1` | Created by |
+| 6 | `AR2:AV2` | `AW2:BC2` | Created date |
+| 7 | `AR3:AV3` | `AW3:BC3` | Revised by |
+| 8 | `AR4:AV4` | `AW4:BC4` | Revised date |
+
+Also keep document title block:
+- `A1:P4` = document title area.
+
+### 4.2 Mandatory Section Order
+
+Each API sheet must keep this order:
+1. Process flow section
+2. `Parameters:`
+3. Request parameter section (JSON format)
+4. Success response section (JSON format)
+5. Error response section (JSON format)
+
+### 4.3 Endpoint Title Placement
+
+- Put endpoint summary at top flow area: `B7`.
+  - Format: `<METHOD> <PATH> <summary>`
+- Repeat the same endpoint summary in contract area:
+  - Column `A`, one row above `Parameters:`.
+- Both endpoint strings must be identical.
+
+### 4.4 Flowchart Placement
+
+- Put PlantUML text in `BG8` (multi-line content in one cell).
+- `BG6` can contain tool/reference note.
+- Helper + main flows can be placed in one cell value if clearly separated.
+- Flow syntax/content standards follow:
+  - `Example/Docs/API/FLOWCHART_CREATION_RULES.md`
+
+## 5. Endpoint and Parameter Rules
+
+### 5.1 Path Parameter Block
+
+- Anchor row: column `B` equals `Parameters:`.
+- Parameter rows:
+  - parameter key in column `C`
+  - description in column `K`
+- Include every path placeholder from endpoint path.
+- Keep parameter order aligned with placeholder order.
+
+### 5.2 Consistency Checks
+
+- Every `{placeholder}` in path must exist exactly once in the parameter rows.
+- Avoid duplicate parameter names unless explicitly documented.
+- Remove stale parameter rows after endpoint rename.
+
+## 6. Request/Response Table Rules
+
+### 6.1 Common Column Model
+
+| No | Column Group | Meaning |
+| ---: | --- | --- |
+| 1 | `A:B` | Row No |
+| 2 | `C:J` | Item label |
+| 3 | `K:N` | Hierarchy level 1 |
+| 4 | `O:R` | Hierarchy level 2 |
+| 5 | `S:V` | Hierarchy level 3 |
+| 6 | `W:Z` | Hierarchy level 4 |
+| 7 | `AA:AD` | Hierarchy level 5 |
+| 8 | `AE:AH` | Hierarchy level 6 |
+| 9 | `AI:AK` | Data type |
+
+### 6.2 Request Header Mode
+
+For write/search request tables, include:
+- `No`
+- `Item Name`
+- `Item`
+- `Type`
+- `Format`
+- `Length`
+- `Required`
+
+Column groups:
+- `AL:AN` -> `Format`
+- `AO:AP` -> `Length`
+- `AQ:AR` -> `Required`
+
+### 6.3 Response Header Mode
+
+For response tables, include:
+- `No`
+- `Item Name`
+- `Item`
+- `Type`
+- `Note`
+
+Column group:
+- `AL:AN` -> `Note`
+
+### 6.4 GET Request Body Rule
+
+- If API has no JSON request body, set request body to:
+  - `None`
+
+### 6.5 Hierarchy Modeling Rule
+
+- Use hierarchy columns (level 1 to level 6) to represent nesting.
+- Represent root wrapper explicitly (for example `data`).
+- For array object children, define parent array node first, then child fields at deeper levels.
+
+## 7. Status and Error Contract Rules
+
+- Success response must include `status` at minimum.
+- Error response must include:
+  - `status`
+  - `data` (message or detail payload)
+- If status detail references an external code table, note that in response notes.
+
+## 8. Type and Format Rules
+
+- Use stable type keywords:
+  - `string`
+  - `integer`
+  - `number`
+  - `object`
+  - `array`
+- If datetime format is constrained, write it in `Format` or `Note` (for example `yyyymmddHHMMSS`).
+- Business constraints (constant flags, nullable behavior, etc.) go to `Note`.
+
+## 9. Recommended Generation Procedure
+
+1. Duplicate an existing API detail sheet.
+2. Update metadata fields (`Q..BC` blocks).
+3. Update endpoint title in `B7`.
+4. Update PlantUML in `BG8`.
+5. Update repeated endpoint title above `Parameters:`.
+6. Update path parameters (`C/K` rows).
+7. Update request section:
+   - `None` for no-body APIs.
+   - request table for body APIs.
+8. Update success response table.
+9. Update error response table.
+10. Append one new row in `History`.
+
+## 10. Quality Gate Checklist Before Handoff
+
+- Section order is complete and unchanged.
+- Endpoint title in `B7` matches the endpoint title above `Parameters:`.
+- Path placeholders and parameter rows are 1:1 matched.
+- Request/response sections use correct header mode.
+- `No` is sequential in every table.
+- Hierarchy columns reflect actual payload nesting.
+- `status` and error payload structure are documented.
+- PlantUML in `BG8` matches endpoint behavior.
+- `History` has a new appended entry.
+
+## 11. Known Pitfalls and Prevention
+
+| No | Pitfall | Prevention Rule |
+| ---: | --- | --- |
+| 1 | Endpoint placeholder renamed but parameter rows not synced | Run path-vs-parameter check for every API sheet |
+| 2 | Request/response headers mixed (`Note` vs `Required`) | Use section-specific header mode only |
+| 3 | Nested array fields placed at wrong hierarchy level | Define parent array first, then child fields deeper |
+| 4 | Endpoint summary mismatch between top and contract blocks | Maintain a single canonical endpoint title string and reuse it |
+