sdtk-kit 0.3.7 → 0.3.8

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/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,12 +77,19 @@ 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`.
@@ -158,6 +193,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

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

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

@@ -0,0 +1,28 @@
+# BA to ARCH Handoff
+
+## Required Inputs
+- `docs/specs/BA_SPEC_[FEATURE_KEY].md`
+- `docs/product/PRD_[FEATURE_KEY].md`
+- `docs/product/BACKLOG_[FEATURE_KEY].md`
+- current `SHARED_PLANNING.md`
+
+## Required Outputs
+- `docs/architecture/ARCH_DESIGN_[FEATURE_KEY].md`
+- API, DB, and UI design artifacts when in scope
+- updated `SHARED_PLANNING.md`
+- updated `QUALITY_CHECKLIST.md`
+
+## Mandatory Checks
+- `REQ -> UC/BR/AC` traceability exists in BA output.
+- unresolved `OQ-xx` items are visible to ARCH.
+- ARCH knows whether API, DB, and UI scope are required.
+
+## Forbidden Shortcuts
+- Do not jump into implementation details before architecture scope is mapped.
+- Do not hide unresolved business rules inside architecture assumptions.
+
+## Handoff Message Shape
+- Feature: `[FEATURE_KEY]`
+- In-scope use cases: `UC-xx`
+- Key business rules: `BR-xx`
+- Blocking open questions: `OQ-xx` or `None`

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

@@ -0,0 +1,26 @@
+# DEV Stage 1 Spec Review
+
+## Required Inputs
+- implementation diff or changed files
+- `docs/specs/BA_SPEC_[FEATURE_KEY].md`
+- `docs/api/[FeaturePascal]_API.yaml` and `docs/api/[FEATURE_KEY]_ENDPOINTS.md` when API scope exists
+- `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md` when UI scope exists
+- `docs/database/DATABASE_SPEC_[FEATURE_KEY].md` when data scope exists
+
+## Required Outputs
+- PASS or FAIL verdict
+- mismatch table with exact file references
+- explicit handoff decision to Stage 2 or back to DEV
+
+## Mandatory Checks
+- code matches BA, API, DB, and flow-action requirements line by line
+- missing mappings and drift are called out explicitly
+- unresolved assumptions that affect behavior are treated as blockers
+
+## Verification Evidence
+- quote the exact specification text before declaring a match or mismatch
+- use: `Spec says: "[exact quote]" -> Evidence: [match/mismatch + file reference]`
+
+## Forbidden Shortcuts
+- Do not start with style or maintainability feedback.
+- Do not trust the implementer report without checking artifacts directly.

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

@@ -0,0 +1,20 @@
+# DEV Stage 2 Code Quality Review
+
+## Required Inputs
+- Stage 1 review result marked PASS
+- implementation diff or changed files
+- relevant test or lint outputs
+
+## Required Outputs
+- PASS or FAIL verdict
+- quality findings with file references
+- recommendation for QA handoff readiness
+
+## Mandatory Checks
+- Stage 1 spec review already passed
+- naming, structure, tests, and maintainability are reviewed
+- verification commands cited are fresh and relevant to the current diff
+
+## Forbidden Shortcuts
+- Do not reopen Stage 1 requirement matching as a substitute for quality review.
+- Do not declare QA-ready without confirming Stage 1 PASS and fresh verification evidence.

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

@@ -0,0 +1,23 @@
+# DEV to QA Handoff
+
+## Required Inputs
+- `docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md`
+- implementation diff summary
+- Stage 1 spec review PASS evidence
+- Stage 2 code-quality review PASS evidence
+- fresh test or lint outputs used for QA handoff
+
+## Required Outputs
+- QA test scope
+- explicit release-risk notes
+- updated `SHARED_PLANNING.md`
+- updated `QUALITY_CHECKLIST.md`
+
+## Mandatory Checks
+- both DEV review gates are PASS
+- verification evidence is fresh
+- known limitations or assumptions are recorded, not hidden
+
+## Forbidden Shortcuts
+- Do not hand off to QA with only one review gate complete.
+- Do not describe expected behavior as if it were verified runtime evidence.

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

@@ -0,0 +1,26 @@
+# PM to BA Handoff
+
+## Required Inputs
+- `docs/product/PROJECT_INITIATION_[FEATURE_KEY].md`
+- source requirement notes or attachments
+- current `SHARED_PLANNING.md`
+
+## Required Outputs
+- `docs/specs/BA_SPEC_[FEATURE_KEY].md`
+- updated `SHARED_PLANNING.md`
+- updated `QUALITY_CHECKLIST.md`
+
+## Mandatory Checks
+- `REQ-xx` scope is explicit and testable.
+- in-scope and out-of-scope are visible.
+- unresolved ambiguities are logged as `OQ-xx`, not hidden.
+
+## Forbidden Shortcuts
+- Do not skip glossary, BR, UC, AC, or traceability expectations.
+- Do not invent missing stakeholder decisions without logging them.
+
+## Handoff Message Shape
+- Feature: `[FEATURE_KEY]`
+- PM scope summary: 3 to 7 bullets
+- Known open questions: `OQ-xx` list or `None`
+- Expected BA focus: rules, use cases, acceptance criteria, NFRs

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

@@ -0,0 +1,21 @@
+# QA Release Decision
+
+## Required Inputs
+- `docs/qa/QA_RELEASE_REPORT_[FEATURE_KEY].md`
+- Stage 1 and Stage 2 DEV review PASS evidence
+- fresh proving checks or benchmark-mode evidence
+- open defect list with severity
+
+## Required Outputs
+- `APPROVED` or `REJECTED`
+- explicit evidence summary
+- unresolved risks and assumptions list
+
+## Mandatory Checks
+- verdict is backed by fresh command evidence or benchmark policy
+- specification quotes are used for requirement-based validation
+- defects and known gaps are visible in the decision
+
+## Forbidden Shortcuts
+- Do not issue `APPROVED` based on planned checks.
+- Do not hide environment limitations; state when runtime verification was not possible.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sdtk-kit",
-    "version": "0.3.7",
+    "version": "0.3.8",
     "description": "SDTK CLI toolkit for deterministic software documentation workflows",
     "bin": {
         "sdtk": "./bin/sdtk.js"