sdtk-kit 0.3.6 → 0.3.8

package/assets/toolkit/toolkit/skills/sdtk-dev/prompts/spec-reviewer.md

@@ -0,0 +1,42 @@
+# SDTK DEV Spec Reviewer Prompt Template
+
+You are the artifact/spec compliance reviewer for a completed SDTK development task.
+
+## Gate Position
+This is Stage 1 review. It runs before the code-quality reviewer.
+
+## Inputs From Controller
+- Task ID: `{{TASK_ID}}`
+- Feature key: `{{FEATURE_KEY}}`
+- Scope summary: `{{SCOPE_SUMMARY}}`
+- Implementer report:
+
+```text
+{{IMPLEMENTER_REPORT}}
+```
+
+- Requirements to validate against:
+
+```text
+{{SPEC_REQUIREMENTS}}
+```
+
+- Files to review:
+
+```text
+{{FILES_TO_REVIEW}}
+```
+
+## Review Rules
+- Do NOT trust implementer report, verify code.
+- Read the actual files listed by the controller.
+- Compare the changed artifacts against the provided BA/API/FLOW_ACTION/DB/plan requirements line by line.
+- Identify missing behavior, incorrect mappings, requirement drift, and unverified assumptions.
+- If artifact compliance fails, do not allow the code-quality review to proceed.
+
+## Response Format
+- Gate result: `{{GATE_RESULT}}`
+- Requirement-by-requirement findings: `{{SPEC_FINDINGS}}`
+- Missing or incorrect artifacts: `{{ARTIFACT_GAPS}}`
+- Required fixes before Stage 2: `{{REQUIRED_FIXES}}`
+- Verification notes: `{{VERIFICATION_NOTES}}`

package/assets/toolkit/toolkit/skills/sdtk-dev-backend/SKILL.md

@@ -5,6 +5,10 @@ description: Generate/modify Python Django REST Framework backend code following
 
 # SDTK Backend (Toolkit conventions)
 
+## Critical Constraints
+- I do not generate backend code without approved API and data-contract sources.
+- I do not ignore established repository patterns when adding backend modules.
+
 ## Process
 1. Check whether this repository already has a backend reference module and follow its patterns.
 2. Follow module structure: `src/backend/<module>/{models,view,service,serializers,validation,enum,urls.py}`.

package/assets/toolkit/toolkit/skills/sdtk-dev-frontend/SKILL.md

@@ -5,6 +5,10 @@ description: Generate/modify React frontend code following the toolkit conventio
 
 # SDTK Frontend (Toolkit conventions)
 
+## Critical Constraints
+- I do not implement screens without current layout and flow-action sources.
+- I do not bypass existing frontend patterns for loading, permissions, or labels.
+
 ## Process
 1. Check whether this repository already has a frontend reference module and follow its patterns.
 2. Follow structure:

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

@@ -5,6 +5,10 @@ description: Orchestrate a full 6-phase SDLC multi-agent workflow (PM/BA/ARCH/DE
 
 # SDTK Orchestrator (multi-agent workflow)
 
+## Critical Constraints
+- I do not skip mandatory phases or hand off without current-phase evidence.
+- I do not treat planned commands as equivalent to completed work.
+
 ## Initialize
 - Ensure feature key + feature name exist (ask if missing).
 - Read `sdtk.config.json` (project stack + commands) if present.
@@ -21,7 +25,7 @@ description: Orchestrate a full 6-phase SDLC multi-agent workflow (PM/BA/ARCH/DE
   - If phase is QA and test-case specification is in scope, invoke `sdtk-test-case-spec` to produce/update `docs/qa/[FEATURE_KEY]_TEST_CASE.md`.
   - Update `SHARED_PLANNING.md` (phase row + activity log).
   - Update `QUALITY_CHECKLIST.md` (mark items PASS/Pending).
-  - Produce one clear handoff message to the next role.
+  - Produce one clear handoff message to the next role only after the current phase evidence supports that handoff.
 
 ## API design detail mode (Hybrid)
 - Read `sdtk.config.json` key: `orchestration.apiDesignDetailMode`.
@@ -37,8 +41,40 @@ description: Orchestrate a full 6-phase SDLC multi-agent workflow (PM/BA/ARCH/DE
   - `on`: always run `sdtk-test-case-spec` for QA phase (fail fast if required inputs are missing).
   - `off`: skip test-case spec generation unless user explicitly requests it.
 
+## Flow Overview
+
+```dot
+digraph sdtk_orchestrator_flow {
+  rankdir=LR;
+  PM -> BA;
+  BA -> ARCH;
+  ARCH -> DEV;
+  DEV -> QA;
+  QA -> PM;
+}
+```
+
+## Verification Before Completion
+Apply `governance/ai/core/SDTK_VERIFICATION_BEFORE_COMPLETION_POLICY.md` whenever you mark a phase complete, mark a gate PASS, or hand off to the next role. Require fresh verification evidence before you state that the phase is done.
+
+Do not:
+- say a phase is done or PASS without citing the evidence that proves it
+- treat a planned command as equivalent to an executed command
+- hand off DEV or QA work with overstated verification status
+
+If the evidence is incomplete, keep the phase open or mark it blocked instead of overstating completion.
+
 ## Guardrails
 - Do not skip phases; if prerequisites are missing, ask focused questions.
 - Keep traceability: REQ -> BR/UC/AC -> design -> backlog -> code/tests -> QA report.
 - Require code review completion before QA handoff.
-- If input requirements are VI/JP: preserve original text + add EN translation in appendix for traceability (at least in Project Initiation and BA spec).
+- If input requirements are VI/JP: preserve original text + add EN translation in appendix for traceability (at least in Project Initiation and BA spec).
+
+
+## Common Mistakes
+
+| Mistake | Why it is wrong | Do instead |
+|---|---|---|
+| Skip directly from PM to DEV because the request seems small | Breaks traceability and removes BA and ARCH controls | Keep phase order unless the user explicitly narrows scope with acceptable evidence |
+| Hand off a phase based on planned checks instead of executed evidence | Creates false PASS status and weakens downstream gates | Require fresh evidence before marking the phase complete |
+| Mix generation, review, and release decisions in one uncontrolled turn | Makes status tracking ambiguous | Complete one phase handoff at a time and update shared state before moving on |

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

@@ -5,6 +5,10 @@ description: Product Manager + meta-orchestrator workflow for SDTK. Use when you
 
 # SDTK PM (Entry Point + Planning)
 
+## Critical Constraints
+- I do not hand off PM work until `SHARED_PLANNING.md` and `QUALITY_CHECKLIST.md` reflect the current phase.
+- I do not hide unresolved scope or decision gaps; I record them as `OQ-xx` items for downstream roles.
+
 ## Outputs
 - Phase 1: `docs/product/PROJECT_INITIATION_[FEATURE_KEY].md`
 - Phase 2+ (after BA spec): `docs/product/PRD_[FEATURE_KEY].md` + `docs/product/BACKLOG_[FEATURE_KEY].md`

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

@@ -5,19 +5,49 @@ description: QA workflow for SDTK. Use when you need to validate an implemented
 
 # SDTK QA (Testing + Release Decision)
 
+## Critical Constraints
+- I do not start QA handoff or release decision work until both DEV review gates PASS.
+- I do not approve without exact specification quotes and fresh verification evidence.
+
 ## Output
 - `docs/qa/QA_RELEASE_REPORT_[FEATURE_KEY].md`
 - Optional (when detailed test design spec is requested):
   - `docs/qa/[FEATURE_KEY]_TEST_CASE.md` via `sdtk-test-case-spec`
 
 ## Process
-1. Validate prerequisites: DEV phase completed + code review PASS.
+1. Validate prerequisites: DEV phase completed + Stage 1 artifact/spec review PASS + Stage 2 code-quality review PASS.
 2. Create test strategy mapped to UC/AC.
 3. If test-case specification artifact is required, invoke `sdtk-test-case-spec` and align counts/coverage with release testing scope. Keep the structured TEST_CASE total consistent with the release-report baseline; track E2E separately if needed.
 4. Apply `governance/ai/core/SDTK_BENCHMARK_QA_MODE_POLICY.md` for benchmark-mode verdict rules when no executable build exists.
 5. If acceptance criteria / expected behavior is unclear, record OQ-xx in QA report and preserve benchmark-expected ambiguity per `governance/ai/core/SDTK_BENCHMARK_OQ_POLICY.md`; escalate to `@pm` if still missing info.
-6. Execute/record results (unit/integration/e2e as applicable).
-7. Record defects with severity and status.
-8. Decide: APPROVED vs REJECTED (with reasons).
-9. Update shared state + Phase 5 checklist.
-10. Handoff: `@pm please finalize release status ...` if approved.
+6. Execute the required checks, record the commands used, and capture the actual results (unit/integration/e2e or document review evidence as applicable).
+7. When validating requirement behavior, quote the exact specification text before recording a match or mismatch.
+8. Record defects with severity and status.
+9. Decide: APPROVED vs REJECTED only after fresh verification evidence supports the verdict.
+10. Update shared state + Phase 5 checklist.
+11. Handoff: `@pm please finalize release status ...` if approved.
+
+## Verification Before Completion
+Apply `governance/ai/core/SDTK_VERIFICATION_BEFORE_COMPLETION_POLICY.md` and require fresh verification evidence before any QA verdict or handoff.
+
+Do not:
+- issue an APPROVED verdict without fresh verification evidence
+- infer PASS from expected behavior, partial logs, or missing runtime access
+- overstate benchmark-mode results as if they were live execution results
+
+If the environment cannot run the proving checks, follow the benchmark QA mode policy explicitly and state that the result is not fully verified at runtime.
+
+## Specification Quoting
+When validating a requirement, quote the exact source text before judging the evidence.
+
+Use this format:
+- `Spec says: "[exact quote]" -> Evidence: [match/mismatch + file reference]`
+
+Apply it to BA, PRD or BACKLOG, ARCH, API, DB, and flow-action sources whenever they define the expected behavior.
+
+## Order-Critical Hard Gate
+Do not start QA handoff, release testing, or release decision work until both DEV review gates are documented as PASS:
+- Stage 1 artifact/spec compliance review
+- Stage 2 code-quality review
+
+If either review gate is missing or not PASS, keep the work in DEV and block QA handoff until both gates are complete.

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

@@ -5,6 +5,10 @@ description: Create/update screen flow-action specifications from requirement so
 
 # 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.
+
 ## Outputs
 - `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`
 - Optional supporting docs:
@@ -30,7 +34,7 @@ description: Create/update screen flow-action specifications from requirement so
 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 generated layout)
+   - Add screen image reference (from Figma, screenshot, or rendered `.svg` from generated layout)
    - Add UI item/action table with `No` column
    - Add API mapping table (trigger -> API -> data usage)
 6. Build/update `System processing flow` from use-case and process sources.
@@ -38,13 +42,16 @@ description: Create/update screen flow-action specifications from requirement so
 8. Build/update `Screen - API Mapping` summary section.
 9. Validate:
    - global numbering consistency (no screen-level reset)
-   - no broken image paths
+   - no broken image paths (for `generated-draft` screens, verify `.svg` exists or use render-skipped note)
    - PlantUML renderability
    - 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
    - every UI-scope screen declares a Design Source Type (`source-backed` or `generated-draft`)
-10. Update document history and handoff to ARCH/DEV.
+10. For `generated-draft` screens, set `Screen image:` to the rendered `.svg` path if the file exists:
+    - Expected path: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
+    - If the `.svg` does not exist (render unavailable), replace the image reference with: `> Screen image not rendered in this environment. See Design Source Reference for layout.`
+11. Update document history and handoff to ARCH/DEV.
 
 ## Rule References
 - Core rules: `./references/FLOW_ACTION_SPEC_CREATION_RULES.md`

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/references/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`.
@@ -115,6 +150,17 @@ Rules:
 - Store images in repository-relative paths.
 - Do not keep temporary local absolute paths in markdown.
 
+### 8.1 Rendered Screen Images for Generated-Draft Screens
+
+When `Design Source Type` is `generated-draft`:
+- Screen preview images may be rendered from `DESIGN_LAYOUT_[FEATURE_KEY].md` PlantUML SALT wireframes.
+- Renderer: `toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py`
+- Expected output path: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
+- If the rendered `.svg` file exists, use it as the `Screen image:` reference.
+- If rendering is unavailable or the `.svg` does not exist, replace the image line with:
+  `> Screen image not rendered in this environment. See Design Source Reference for layout.`
+- Do not leave a broken image reference pointing to a non-existent file.
+
 ## 9. Consistency with Other Specs
 
 - Align terms with:
@@ -145,8 +191,9 @@ Rules:
 - All mandatory sections exist.
 - All tables include `No`.
 - Numbering is global across the document (no resets).
-- No broken image links.
+- 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/skills/sdtk-test-case-spec/SKILL.md

@@ -5,6 +5,10 @@ description: Generate screen-based QA test-case markdown (`[FEATURE_KEY]_TEST_CA
 
 # SDTK Test Case Spec
 
+## Critical Constraints
+- I do not invent test coverage beyond BA, flow-action, and API sources.
+- I do not let test totals drift away from worksheet rows or the QA baseline.
+
 ## Outputs
 - `docs/qa/[FEATURE_KEY]_TEST_CASE.md`
 - Optional project variant:
@@ -28,6 +32,7 @@ description: Generate screen-based QA test-case markdown (`[FEATURE_KEY]_TEST_CA
 4. Keep one unified 18-column schema for UTC/ITC rows.
 5. Keep stable case IDs; do not renumber only because of regrouping.
 6. Track unresolved decisions via `OQ-xx` and keep benchmark-expected OQs explicitly OPEN per `governance/ai/core/SDTK_BENCHMARK_OQ_POLICY.md`.
+7. Quote exact BA, API, or flow-action requirement text when a testcase or coverage claim depends on that requirement.
 
 ## Procedure
 1. Resolve output path:
@@ -44,6 +49,12 @@ description: Generate screen-based QA test-case markdown (`[FEATURE_KEY]_TEST_CA
    - no placeholder tokens like `??`
    - out-of-scope boundaries are explicit
 
+## Specification Quoting
+When a testcase, coverage note, or defect check depends on a requirement, quote the exact source text before stating coverage or mismatch.
+
+Use this format:
+- `Spec says: "[exact quote]" -> Evidence: [covered/not covered + file reference]`
+
 ## Role Integration
 - Primary owner: `/qa`.
 - `/qa` uses this skill to design/update reusable test-case specs.