@warnyin/agents 0.10.0 → 0.11.0

package/src/.warnyin/workflow/stages/build.md

@@ -1,98 +1,98 @@
-# Stage: BUILD
-
-> **Playbook กลาง — AI ทุกเจ้าทำตามไฟล์นี้ชุดเดียวกัน** (Claude Code / Codex / Antigravity / อื่นๆ)
-> เป้าหมาย: ลงมือทำ task ที่ DESIGN เตรียมไว้ โดย **fan-out sub-agent อัตโนมัติต่อ task ตาม dependency**
-> **Context profile:** สวมโหมด `build` (`.warnyin/workflow/contexts/build.md`) — session-level posture ของ stage นี้
-
----
-
-## 1. BUILD คืออะไร / ใช้เมื่อไหร่
-
-ใช้เมื่อ DESIGN ผ่าน Gate แล้ว มี `tasks/<task>/` ครบ (task.md + spec.md + standard.md + rule.md)
-BUILD จะ **orchestrate การ implement** โดยกระจายงานเป็น sub-agent หนึ่งตัวต่อหนึ่ง task/slice และเดินตาม dependency graph
-
----
-
-## 2. Input ที่ต้องอ่านก่อนเริ่ม
-
-1. `docs/stages/<slug>/design.md` — dependency graph ระหว่าง task/slice (section 7)
-2. `docs/stages/<slug>/proposal.md` — scope ของ change
-3. `docs/stages/<slug>/tasks/<task>/task.md` ทุกใบ — dependency ของแต่ละ task + sub-tasks
-4. `docs/techstack/<component>/rule.md` + `standard.md` — กฎ/มาตรฐานที่ต้อง follow
-
----
-
-## 3. หลักการทำงาน (operating principles)
-
-1. **ถาม user ยืนยัน "ครั้งเดียวก่อนเริ่ม"** — แสดง execution plan (DAG + wave ไหนรัน parallel + isolation) ให้ user อนุมัติ แล้วจึง fan-out อัตโนมัติ ไม่ถามซ้ำระหว่างทาง
-2. **Fan-out ตาม dependency (wave-based)** — จัด task เป็น "wave" ตาม topological order ของ dependency:
-   - task ใน wave เดียวกัน = independent → รัน **parallel**
-   - ข้าม wave = มี dependency → wave ถัดไปเริ่มหลัง wave ก่อนหน้ารวมผลเสร็จ
-3. **Worktree isolation ต่อ task** — แต่ละ parallel task ทำใน git worktree ของตัวเอง ไม่แก้ไฟล์ชนกัน แล้ว **integrate (merge) เข้า build branch หลังจบแต่ละ wave**
-   - **★ worktree fork จาก main (คุมไม่ได้) → agent ต้อง sync build branch ก่อน** — harness fork worktree จาก main จึงยังไม่เห็น `docs/stages/<slug>/` (topic docs) + output ของ wave ก่อนหน้า; build-wave สั่ง agent `git merge <baseRef>` (= build branch) เป็น step แรกก่อนอ่าน task เพื่อให้เห็น dependency ครบ (กลไกอยู่ใน `build-wave.mjs` — orchestrator ส่ง `baseRef` เข้ามา)
-   - ถ้า target ไม่ใช่ git repo → fallback เป็น **sequential shared-tree** (ทีละ task ตาม dependency)
-4. **แต่ละ build agent ต้อง self-verify** — implement → รัน test-flow ใน `spec.md` + build/lint → **ต้องผ่านก่อนถึง mark passed**; ถ้าแก้ไม่ได้ให้รายงาน `failed` พร้อมเหตุผล **ห้ามรายงานผ่านทั้งที่ยังแดง**
-5. **เคารพ standard/rule ของ task** — ทำตาม `standard.md` (pattern โค้ด, reuse shared component) และ `rule.md` (กฎ) อย่างเคร่งครัด
-6. **ห้ามแตะ rule/standard กลางใน `docs/`** — rule ใหม่ที่เสนอถูก note ไว้ใน `tasks/<task>/rule.md` แล้ว รอ SHIP ค่อยอัปเดตไฟล์กลาง
-7. **fail = หยุดที่ wave นั้น** — ถ้า task ใน wave ล้ม ให้รายงาน user ก่อนไป wave ถัดไป (เพราะ wave ถัดไปอาจ depend อยู่)
-8. **★ ปิดท้ายด้วย full build + full test เสมอ** — หลัง merge ทุก wave แล้ว ต้องรัน build ทั้งหมด + test suite ทั้งหมด (รวม unit test) บน build branch ที่ integrate; **แก้วนจนเขียวหมด** ก่อนปิด BUILD (กันกรณี task รายเดี่ยวเขียวแต่พอรวมกันแล้วพัง)
-9. **ทุก build agent สวม role Developer** — ทำตาม role card `.warnyin/workflow/roles/developer.md` (lens + checklist ก่อนส่งงาน) — build-wave.mjs ใส่ให้ใน prompt แล้ว
-10. **★ ใช้ Troubleshooting KB** — เจอปัญหา/error ระหว่าง build ให้ **อ่าน `docs/troubleshooting.md` ก่อนเสมอ** เผื่อเคยแก้แล้ว; เมื่อแก้ปัญหาที่ **ยาก/เจอซ้ำ** สำเร็จ ให้บันทึก entry ลง `docs/stages/<slug>/troubleshooting.md` (ปัญหา/อาการ/root cause/วิธีแก้/ป้องกันซ้ำ) — ตอน SHIP จะยกขึ้น KB กลาง
-11. **★ investigate-before-edit** (enforce ของ "ห้ามเดา") — ก่อนแก้ไฟล์ที่มีอยู่ ต้องเข้าใจก่อน — **ใครใช้/อ่านไฟล์นี้, schema/contract/สัญญาของมัน, เจตนาเดิม**; แก้โดยไม่เข้าใจ = เดา (กรณีไม่ชัด → ถาม user / อ่านโค้ดที่อ้างถึง ก่อนแก้)
-12. **★ config-protection** (enforce ของ "ห้ามเดา") — ห้ามแก้ config (linter/formatter/test threshold) หรือ disable rule **"เพื่อให้ build/test ผ่าน"** แทนการแก้โค้ดจริง — ถ้า config ผิดจริง แก้ได้แต่ต้องมี **เหตุผลชัด + note** (ไม่ใช่เพื่อเลี่ยง finding)
-
----
-
-## 4. ลำดับขั้นการทำงาน (orchestration)
-
-> ผู้ orchestrate คือ AI ตัวหลัก (main loop) — sub-agent คือคนลงมือ implement
-
-0. **★ เช็ค context window ก่อนเริ่ม:** ประเมินว่า context ของ session ปัจจุบันถูกใช้ไปมากน้อยแค่ไหน — ถ้าใช้ไปเยอะหรือ **เกินครึ่ง** → **เสนอ user ให้ `/compact` หรือ `/clear` ก่อนเสมอ** แล้วค่อยเริ่ม BUILD ใน context ที่โล่ง (สถานะงานอยู่ในไฟล์ `docs/stages/<slug>/` ครบ ไม่หายไปกับ context) — BUILD เป็นงานยาว ต้องมี context เหลือมากพอ; เครื่องอื่นที่ไม่มีคำสั่งนี้ → แนะนำเริ่ม session ใหม่
-1. **อ่าน task ทั้งหมด** → ดึง dependency ของแต่ละ task จาก `task.md` (section 2) + `design.md` (section 7)
-2. **สร้าง DAG + จัด wave** (topological sort): wave 1 = task ที่ไม่มี dependency, wave 2 = task ที่ depend เฉพาะ wave 1, ...
-3. **Pre-check:** target เป็น git repo ไหม (สำหรับ worktree) — ถ้าไม่ใช่ → fallback sequential shared-tree และแจ้ง user
-4. **เสนอ execution plan + ขออนุมัติ (ครั้งเดียว):** แสดง wave / task ในแต่ละ wave / อันไหน parallel / isolation mode → ถาม user go/no-go
-5. **เดินทีละ wave:**
-   - fan-out sub-agent ของ task ใน wave นั้น (parallel, worktree isolation) ผ่าน **Workflow** (`.warnyin/workflow/scripts/build-wave.mjs`) — orchestrator **ส่ง `baseRef` (= build branch)** เข้า build-wave เพื่อให้ agent sync build branch เข้า worktree ก่อน (เห็น topic docs + output wave ก่อนหน้า)
-   - แต่ละ agent: sync build branch (`git merge <baseRef>`) → implement → test/lint → commit (ถ้า worktree) → รายงานผลแบบ structured (status, files, branch, test result)
-   - **integrate:** main loop checkout **เฉพาะไฟล์ source ที่ scoped** ของ wave นั้นจาก worktree branch (`git checkout <branch> -- <files>` — เลี่ยง topic-docs copy ที่ agent merge เข้า worktree + ปลอด KB#11); ถ้า conflict → แก้/รายงาน
-   - ถ้ามี task `failed` → หยุด รายงาน user
-6. **★ Full build & test gate (หลังทุก wave merge เสร็จ):** บน build branch ที่ integrate แล้ว รัน **build ทั้งหมด + test suite ทั้งหมด (รวม unit test)** ของทุก component ที่กระทบ
-   - มี error / test แดง → **แก้จนเขียวหมด (loop)** อาจ delegate fix ให้ sub-agent ทีละจุด แล้ว rerun ใหม่
-   - **ห้ามปิด BUILD ถ้ายังมี build error หรือ test ตัวใดแดง**
-   - ถ้าวนแก้หลายรอบยังไม่ผ่าน → หยุด รายงาน user พร้อม log error
-7. **ปิดงาน:** อัปเดต `build.md` (รายงานผลต่อ task + ผล full build/test) + สถานะใน `task.md` แต่ละใบ → เสนอเข้า VERIFY ด้วย `/warnyin:verify`
-
----
-
-## 5. Output
-
-| ไฟล์ | เนื้อหา |
-|---|---|
-| โค้ดจริงใน target repo | การ implement ของแต่ละ task (merge เข้า build branch) |
-| `docs/stages/<slug>/build.md` | รายงานผล build: สถานะ/ผล test/ไฟล์ที่แก้ ต่อ task + integration notes |
-| `docs/stages/<slug>/troubleshooting.md` | ปัญหายาก/ซ้ำที่แก้สำเร็จ (SHIP ยกขึ้น `docs/troubleshooting.md`) |
-| `tasks/<task>/task.md` (อัปเดต) | สถานะ task → เสร็จ + acceptance ที่ผ่าน |
-
----
-
-## 6. Workflow script (Claude Code)
-
-ใช้ `.warnyin/workflow/scripts/build-wave.mjs` — fan-out หนึ่ง agent ต่อหนึ่ง task ใน **หนึ่ง wave** (parallel, worktree isolation), คืนผลแบบ structured
-main loop เรียก script นี้ **ทีละ wave** แล้ว integrate ระหว่าง wave (ดูรายละเอียดใน `.claude/commands/warnyin/build.md`)
-
-> เครื่องอื่น (Codex/Antigravity) ที่ไม่มี Workflow tool: ทำตามหลักการข้อ 3-4 โดย implement task ตามลำดับ wave เอง (parallel เท่าที่เครื่องรองรับ)
-
----
-
-## 7. Gate → เข้า VERIFY ได้เมื่อ
-
-- [ ] ทุก task ใน DAG ถูก implement และ merge เข้า build branch แล้ว
-- [ ] ทุก task รายงาน `passed` (test-flow + build/lint เขียว) — ไม่มี `failed` ค้าง
-- [ ] ไม่มี merge conflict ค้าง
-- [ ] **★ Full build ของทุก component ผ่าน — ไม่มี build error**
-- [ ] **★ test suite ทั้งหมด (รวม unit test) เขียวทั้งหมดบน build branch**
-- [ ] `build.md` สรุปผลครบทุก task + ผล full build/test
-- [ ] ไม่มีการแตะ rule/standard กลางใน `docs/` (rule ใหม่ยัง note รอ SHIP)
-
-ยังไม่ครบ → อยู่ BUILD ต่อ ห้ามข้ามไป VERIFY
+# Stage: BUILD
+
+> **Playbook กลาง — AI ทุกเจ้าทำตามไฟล์นี้ชุดเดียวกัน** (Claude Code / Codex / Antigravity / อื่นๆ)
+> เป้าหมาย: ลงมือทำ task ที่ DESIGN เตรียมไว้ โดย **fan-out sub-agent อัตโนมัติต่อ task ตาม dependency**
+> **Context profile:** สวมโหมด `build` (`.warnyin/workflow/contexts/build.md`) — session-level posture ของ stage นี้
+
+---
+
+## 1. BUILD คืออะไร / ใช้เมื่อไหร่
+
+ใช้เมื่อ DESIGN ผ่าน Gate แล้ว มี `tasks/<task>/` ครบ (task.md + spec.md + standard.md + rule.md)
+BUILD จะ **orchestrate การ implement** โดยกระจายงานเป็น sub-agent หนึ่งตัวต่อหนึ่ง task/slice และเดินตาม dependency graph
+
+---
+
+## 2. Input ที่ต้องอ่านก่อนเริ่ม
+
+1. `docs/stages/<slug>/design.md` — dependency graph ระหว่าง task/slice (section 7)
+2. `docs/stages/<slug>/proposal.md` — scope ของ change
+3. `docs/stages/<slug>/tasks/<task>/task.md` ทุกใบ — dependency ของแต่ละ task + sub-tasks
+4. `docs/techstack/<component>/rule.md` + `standard.md` — กฎ/มาตรฐานที่ต้อง follow
+
+---
+
+## 3. หลักการทำงาน (operating principles)
+
+1. **ถาม user ยืนยัน "ครั้งเดียวก่อนเริ่ม"** — แสดง execution plan (DAG + wave ไหนรัน parallel + isolation) ให้ user อนุมัติ แล้วจึง fan-out อัตโนมัติ ไม่ถามซ้ำระหว่างทาง
+2. **Fan-out ตาม dependency (wave-based)** — จัด task เป็น "wave" ตาม topological order ของ dependency:
+   - task ใน wave เดียวกัน = independent → รัน **parallel**
+   - ข้าม wave = มี dependency → wave ถัดไปเริ่มหลัง wave ก่อนหน้ารวมผลเสร็จ
+3. **Worktree isolation ต่อ task** — แต่ละ parallel task ทำใน git worktree ของตัวเอง ไม่แก้ไฟล์ชนกัน แล้ว **integrate (merge) เข้า build branch หลังจบแต่ละ wave**
+   - **★ worktree fork จาก main (คุมไม่ได้) → agent ต้อง sync build branch ก่อน** — harness fork worktree จาก main จึงยังไม่เห็น `docs/stages/<slug>/` (topic docs) + output ของ wave ก่อนหน้า; build-wave สั่ง agent `git merge <baseRef>` (= build branch) เป็น step แรกก่อนอ่าน task เพื่อให้เห็น dependency ครบ (กลไกอยู่ใน `build-wave.mjs` — orchestrator ส่ง `baseRef` เข้ามา)
+   - ถ้า target ไม่ใช่ git repo → fallback เป็น **sequential shared-tree** (ทีละ task ตาม dependency)
+4. **แต่ละ build agent ต้อง self-verify (scope = component ตัวเองเท่านั้น)** — implement → รัน test-flow ใน `spec.md` + build/lint **ของ component ที่ task นั้นแตะ (unit + lint ของ component นั้น) ไม่ใช่ทั้ง repo** → **ต้องผ่านก่อนถึง mark passed**; ถ้าแก้ไม่ได้ให้รายงาน `failed` พร้อมเหตุผล **ห้ามรายงานผ่านทั้งที่ยังแดง** — **cross-component / integration / e2e ไม่ต้องรันต่อ task** (เลื่อนไป full-gate ข้อ 8 / §4 ข้อ 6) กันรันซ้ำเสียเวลา
+5. **เคารพ standard/rule ของ task** — ทำตาม `standard.md` (pattern โค้ด, reuse shared component) และ `rule.md` (กฎ) อย่างเคร่งครัด
+6. **ห้ามแตะ rule/standard กลางใน `docs/`** — rule ใหม่ที่เสนอถูก note ไว้ใน `tasks/<task>/rule.md` แล้ว รอ SHIP ค่อยอัปเดตไฟล์กลาง
+7. **fail = หยุดที่ wave นั้น** — ถ้า task ใน wave ล้ม ให้รายงาน user ก่อนไป wave ถัดไป (เพราะ wave ถัดไปอาจ depend อยู่)
+8. **★ ปิดท้ายด้วย full build + full test เสมอ (blocking gate — ห้ามลด bar)** — หลัง merge ทุก wave แล้ว ต้องรัน build ทั้งหมด + test suite ทั้งหมด (รวม unit test) + cross-component/integration บน build branch ที่ integrate; **แก้วนจนเขียวหมด** ก่อนปิด BUILD (กันกรณี task รายเดี่ยวเขียวแต่พอรวมกันแล้วพัง) — **gate นี้คงเป็น blocking เสมอ** การที่ข้อ 4 ลด self-verify ของ agent เหลือ scope component เดียว **ไม่ได้ลดความเข้มของ full-gate** (integration coverage ย้ายมารวมที่นี่ ไม่ใช่ตัดทิ้ง); ห้ามแปลง gate นี้เป็น optional/informational เพื่อให้ "ดูเร็วขึ้น"
+9. **ทุก build agent สวม role Developer** — ทำตาม role card `.warnyin/workflow/roles/developer.md` (lens + checklist ก่อนส่งงาน) — build-wave.mjs ใส่ให้ใน prompt แล้ว
+10. **★ ใช้ Troubleshooting KB** — เจอปัญหา/error ระหว่าง build ให้ **อ่าน `docs/troubleshooting.md` ก่อนเสมอ** เผื่อเคยแก้แล้ว; เมื่อแก้ปัญหาที่ **ยาก/เจอซ้ำ** สำเร็จ ให้บันทึก entry ลง `docs/stages/<slug>/troubleshooting.md` (ปัญหา/อาการ/root cause/วิธีแก้/ป้องกันซ้ำ) — ตอน SHIP จะยกขึ้น KB กลาง
+11. **★ investigate-before-edit** (enforce ของ "ห้ามเดา") — ก่อนแก้ไฟล์ที่มีอยู่ ต้องเข้าใจก่อน — **ใครใช้/อ่านไฟล์นี้, schema/contract/สัญญาของมัน, เจตนาเดิม**; แก้โดยไม่เข้าใจ = เดา (กรณีไม่ชัด → ถาม user / อ่านโค้ดที่อ้างถึง ก่อนแก้)
+12. **★ config-protection** (enforce ของ "ห้ามเดา") — ห้ามแก้ config (linter/formatter/test threshold) หรือ disable rule **"เพื่อให้ build/test ผ่าน"** แทนการแก้โค้ดจริง — ถ้า config ผิดจริง แก้ได้แต่ต้องมี **เหตุผลชัด + note** (ไม่ใช่เพื่อเลี่ยง finding)
+
+---
+
+## 4. ลำดับขั้นการทำงาน (orchestration)
+
+> ผู้ orchestrate คือ AI ตัวหลัก (main loop) — sub-agent คือคนลงมือ implement
+
+0. **★ เช็ค context window ก่อนเริ่ม:** ประเมินว่า context ของ session ปัจจุบันถูกใช้ไปมากน้อยแค่ไหน — ถ้าใช้ไปเยอะหรือ **เกินครึ่ง** → **เสนอ user ให้ `/compact` หรือ `/clear` ก่อนเสมอ** แล้วค่อยเริ่ม BUILD ใน context ที่โล่ง (สถานะงานอยู่ในไฟล์ `docs/stages/<slug>/` ครบ ไม่หายไปกับ context) — BUILD เป็นงานยาว ต้องมี context เหลือมากพอ; เครื่องอื่นที่ไม่มีคำสั่งนี้ → แนะนำเริ่ม session ใหม่
+1. **อ่าน task ทั้งหมด** → ดึง dependency ของแต่ละ task จาก `task.md` (section 2) + `design.md` (section 7)
+2. **สร้าง DAG + จัด wave** (topological sort): wave 1 = task ที่ไม่มี dependency, wave 2 = task ที่ depend เฉพาะ wave 1, ...
+3. **Pre-check:** target เป็น git repo ไหม (สำหรับ worktree) — ถ้าไม่ใช่ → fallback sequential shared-tree และแจ้ง user
+4. **เสนอ execution plan + ขออนุมัติ (ครั้งเดียว):** แสดง wave / task ในแต่ละ wave / อันไหน parallel / isolation mode → ถาม user go/no-go
+5. **เดินทีละ wave:**
+   - fan-out sub-agent ของ task ใน wave นั้น (parallel, worktree isolation) ผ่าน **Workflow** (`.warnyin/workflow/scripts/build-wave.mjs`) — orchestrator **ส่ง `baseRef` (= build branch)** เข้า build-wave เพื่อให้ agent sync build branch เข้า worktree ก่อน (เห็น topic docs + output wave ก่อนหน้า)
+   - แต่ละ agent: sync build branch (`git merge <baseRef>`) → implement → test/lint → commit (ถ้า worktree) → รายงานผลแบบ structured (status, files, branch, test result)
+   - **integrate:** main loop checkout **เฉพาะไฟล์ source ที่ scoped** ของ wave นั้นจาก worktree branch (`git checkout <branch> -- <files>` — เลี่ยง topic-docs copy ที่ agent merge เข้า worktree + ปลอด KB#11); ถ้า conflict → แก้/รายงาน
+   - ถ้ามี task `failed` → หยุด รายงาน user
+6. **★ Full build & test gate (หลังทุก wave merge เสร็จ — blocking, ห้ามลด bar):** บน build branch ที่ integrate แล้ว รัน **build ทั้งหมด + test suite ทั้งหมด (รวม unit test) + cross-component/integration** ของทุก component ที่กระทบ — นี่คือจุดที่ครอบ integration ที่ self-verify ต่อ task (§3 ข้อ 4) ไม่ได้รัน จึง **ต้องคงเป็น blocking gate เต็มเสมอ**
+   - มี error / test แดง → **แก้จนเขียวหมด (loop)** อาจ delegate fix ให้ sub-agent ทีละจุด แล้ว rerun ใหม่
+   - **ห้ามปิด BUILD ถ้ายังมี build error หรือ test ตัวใดแดง**
+   - ถ้าวนแก้หลายรอบยังไม่ผ่าน → หยุด รายงาน user พร้อม log error
+7. **ปิดงาน:** อัปเดต `build.md` (รายงานผลต่อ task + ผล full build/test) + สถานะใน `task.md` แต่ละใบ → เสนอเข้า VERIFY ด้วย `/warnyin:verify`
+
+---
+
+## 5. Output
+
+| ไฟล์ | เนื้อหา |
+|---|---|
+| โค้ดจริงใน target repo | การ implement ของแต่ละ task (merge เข้า build branch) |
+| `docs/stages/<slug>/build.md` | รายงานผล build: สถานะ/ผล test/ไฟล์ที่แก้ ต่อ task + integration notes |
+| `docs/stages/<slug>/troubleshooting.md` | ปัญหายาก/ซ้ำที่แก้สำเร็จ (SHIP ยกขึ้น `docs/troubleshooting.md`) |
+| `tasks/<task>/task.md` (อัปเดต) | สถานะ task → เสร็จ + acceptance ที่ผ่าน |
+
+---
+
+## 6. Workflow script (Claude Code)
+
+ใช้ `.warnyin/workflow/scripts/build-wave.mjs` — fan-out หนึ่ง agent ต่อหนึ่ง task ใน **หนึ่ง wave** (parallel, worktree isolation), คืนผลแบบ structured
+main loop เรียก script นี้ **ทีละ wave** แล้ว integrate ระหว่าง wave (ดูรายละเอียดใน `.claude/commands/warnyin/build.md`)
+
+> เครื่องอื่น (Codex/Antigravity) ที่ไม่มี Workflow tool: ทำตามหลักการข้อ 3-4 โดย implement task ตามลำดับ wave เอง (parallel เท่าที่เครื่องรองรับ)
+
+---
+
+## 7. Gate → เข้า VERIFY ได้เมื่อ
+
+- [ ] ทุก task ใน DAG ถูก implement และ merge เข้า build branch แล้ว
+- [ ] ทุก task รายงาน `passed` (test-flow + build/lint เขียว) — ไม่มี `failed` ค้าง
+- [ ] ไม่มี merge conflict ค้าง
+- [ ] **★ Full build ของทุก component ผ่าน — ไม่มี build error**
+- [ ] **★ test suite ทั้งหมด (รวม unit test) เขียวทั้งหมดบน build branch**
+- [ ] `build.md` สรุปผลครบทุก task + ผล full build/test
+- [ ] ไม่มีการแตะ rule/standard กลางใน `docs/` (rule ใหม่ยัง note รอ SHIP)
+
+ยังไม่ครบ → อยู่ BUILD ต่อ ห้ามข้ามไป VERIFY

package/src/.warnyin/workflow/stages/design.md

@@ -1,122 +1,126 @@
-# Stage: DESIGN
-
-> **Playbook กลาง — AI ทุกเจ้าทำตามไฟล์นี้ชุดเดียวกัน** (Claude Code / Codex / Antigravity / อื่นๆ)
-> เป้าหมาย: เสนอ **change ใหม่** พร้อมผลิต artifact ครบในขั้นเดียว — proposal (what & why) → design (how) → tasks (พร้อม execute)
-> **Context profile:** สวมโหมด `research` (`.warnyin/workflow/contexts/research.md`) ช่วงต้น (proposal/design) · `build` (`.warnyin/workflow/contexts/build.md`) ช่วงแตก task — session-level posture ของ stage นี้
-
----
-
-## 1. DESIGN คืออะไร / ใช้เมื่อไหร่
-
-ใช้เมื่อ user อยากอธิบายสิ่งที่จะสร้าง/แก้แบบเร็วๆ แล้วได้ **ข้อเสนอที่สมบูรณ์** — มีทั้งการออกแบบ, spec, และ task ที่พร้อมลงมือทำ
-ครอบคลุม: build change, fix bug, แก้อะไรก็ตามที่เกี่ยวกับ **code / docs**
-
-- **ถ้าเป็นคำถาม หรือยังไม่มั่นใจเรื่อง design → แนะนำให้ใช้ `/warnyin:discovery` ก่อน** แล้วค่อยกลับมา DESIGN
-- ปรับความละเอียด artifact ตามขนาด change (ดูข้อ 7)
-
----
-
-## 2. Input ที่ต้องอ่านก่อนเริ่ม
-
-1. `docs/project.md` — เป้าหมาย/ขอบเขตโปรเจกต์
-2. `docs/rule.md` + `docs/techstack/<component>/rule.md` — ★ กฎที่ต้อง follow
-3. `docs/techstack/<component>/standard.md` — ★ pattern/มาตรฐานการเขียนโค้ด
-4. `docs/techstack/<component>/{about,structure,test}.md`, `docs/codemap/index.md` — โครงสร้าง/วิธีเทสต์
-5. ถ้ามี Discovery → `docs/stages/<slug>/discovery.md`, `research.md`
-6. `docs/features/<name>/spec.md` — ★ behavior spec ปัจจุบันของ feature ที่ change แตะ (baseline สำหรับเขียน Spec delta; feature ยังไม่มี spec → ข้ามได้)
-7. โค้ดจริงที่เกี่ยวข้อง (inspect เพื่อตอบคำถามแทนการเดา)
-
----
-
-## 3. หลักการทำงาน (operating principles)
-
-1. **ห้ามเดาเอง** — จุดที่ไม่มั่นใจ ให้ **ถามทีละข้อ + เสนอคำตอบที่แนะนำ (recommended answer) ทุกข้อ** (เหมือน Discovery) คำถามที่ตอบได้ด้วยโค้ด/เอกสาร → ไปอ่านเอง
-2. **Vertical slice architecture** — ออกแบบและแตก task เป็น "slice ที่ตัดผ่านทุก layer" (UI → API → domain → data → test) ทำงาน end-to-end ได้ในตัว **ไม่แบ่งตาม layer แนวนอน**
-3. **task = หน่วยที่โยนให้ sub-agent ได้** — แต่ละ task self-contained (มี spec + standard + rule ของตัวเอง) แต่ **เชื่อมต่อกัน** ผ่าน dependency/ลำดับที่ระบุชัด
-4. **สอดคล้องมาตรฐานเสมอ** — อิง rule + standard ของ techstack; ถ้าจะเพิ่ม rule/standard ใหม่ ให้ **note ไว้ก่อน** (ยังไม่แก้ไฟล์กลาง — รอ SHIP)
-5. **Gate ก่อนเขียนไฟล์ task จริง** — ต้องผ่านเกณฑ์ข้อ 8 ก่อนจะ generate ไฟล์ task และก่อนโยนให้ sub-agent
-6. **ใช้ role lens** — ออกแบบ (design.md) ด้วยมุม **SA** (`.warnyin/workflow/roles/sa.md`) และแตก/ตรวจ task ด้วยมุม **Tech Lead** (`.warnyin/workflow/roles/tech-lead.md`)
-7. **Review panel ก่อนแตก task (optional — ถาม user ก่อนเสมอ)** — ให้หลาย role (SA / Tech Lead / QA / Security / Infra ตาม `.warnyin/workflow/roles/`) รีวิว design ขนานแบบอิสระ (read-only) แล้วแก้ blocker ให้ครบก่อนแตก task (ดูขั้นตอนข้อ 4.6)
-8. **Dry-run ก่อนเข้า BUILD (optional — ถาม user ก่อนเสมอ)** — หลังเขียนไฟล์ task ครบ เสนอ user ว่าจะ dry-run ทั้งหมดเพื่อหาจุดบกพร่องไหม ถ้า ok → สแกนทุก task แบบขนาน (read-only) หา **defer/blocker** แล้วแก้ DESIGN จนไม่มี blocker ค้าง (ดูขั้นตอนข้อ 4.10) — การแก้ **ห้ามเดา ห้ามคิดขึ้นเอง**
-
----
-
-## 4. ลำดับขั้นการทำงาน (process)
-
-1. **เตรียมพื้นที่:** ใช้/สร้างโฟลเดอร์ `docs/stages/<slug>/` (ถ้ามาจาก Discovery ใช้อันเดิม)
-2. **Ground + เคลียร์ความไม่ชัด:** อ่าน Input; ทุกจุดกำกวมเรื่อง design → ถามทีละข้อ + recommended answer จนชัด (ถ้าใหญ่/ไม่ชัดมาก → แนะนำ Discovery ก่อน)
-3. **business.md** *(optional — ข้ามได้ถ้า change เล็ก เช่น fix bug นิดหน่อย)*: what & why เชิงธุรกิจ — goal, คุณค่า, persona, success metric
-4. **proposal.md** (what & why): สรุป change ที่จะทำ, เหตุผล, ทางเลือกที่พิจารณา/ตัดทิ้ง, scope in/out
-5. **design.md** (how): ออกแบบเชิงเทคนิคแบบ vertical slice — slice มีอะไรบ้าง, แต่ละ slice ตัดผ่าน layer ไหน, data model, interface/contract, flow, ผลกระทบต่อระบบเดิม (ใช้ lens `.warnyin/workflow/roles/sa.md`) — **ครอบ "Spec delta" ด้วย**: เทียบพฤติกรรมที่ change นี้แตะกับ `docs/features/<name>/spec.md` ปัจจุบัน แล้วเขียน ADDED/MODIFIED/REMOVED (SHIP merge ตามนี้); change ไม่แตะพฤติกรรม feature → ระบุ "ไม่มี delta"
-6. **Review panel (optional — ถาม user ก่อน):** เสนอ user ว่าจะให้ panel หลาย role รีวิว design ก่อนแตก task ไหม — ถ้า ok:
-   1. fan-out sub-agent reviewer **ขนาน (read-only)** ตาม role card: **SA** (architecture/data model/contract), **Tech Lead** (feasibility/ขนาด task/dependency), **QA** (testability/acceptance), **Security** (ช่องโหว่/ข้อมูลอ่อนไหว), **Infra** (env/config/migration) — แต่ละตัวอ่าน `proposal.md` + `design.md` + โค้ดจริงที่เกี่ยว แล้วให้ความเห็นตาม checklist ใน `.warnyin/workflow/roles/<role>.md` แบ่งเป็น **blocker / suggestion**
-   2. รวมความเห็นทุก role → สรุปให้ user เห็นภาพ
-   3. **blocker → แก้ design ให้ครบ** โดยห้ามเดา — ติดจริงถาม user ทีละข้อ + เสนอคำตอบแนะนำ; suggestion → พิจารณา/บันทึกเหตุผลถ้าไม่ทำ
-   4. บันทึกสรุปผล panel + สิ่งที่แก้ ลงท้าย `design.md` (section "Design review")
-   5. เครื่องที่ fan-out ไม่ได้ → รีวิวทีละ role ด้วย checklist เดียวกัน
-7. **แตก tasks:** แปลง design เป็น task (= vertical slice / step ที่แก้); task ซับซ้อน → แตก **sub-task** ย่อย; เขียน **dependency graph / ลำดับ** ให้ sub-task เชื่อมกัน
-8. **rule check ต่อ task:** เปิด `docs/techstack/<component>/rule.md` หา rule ที่ task นี้ต้องโฟกัส → ใส่ใน `tasks/<task>/rule.md`; rule ใหม่ที่อยากเพิ่ม → note ใน section "เสนอเพิ่ม (รอ SHIP)"
-9. **เช็ค Gate (ข้อ 8)** → เมื่อผ่าน จึง **เขียนไฟล์ task ครบทุกใบ** (แตก task ด้วย lens `.warnyin/workflow/roles/tech-lead.md`)
-10. **Dry-run (optional — ถาม user ก่อน):** ถาม user ว่าต้องการ dry-run ทั้งหมดเพื่อหาจุดบกพร่องก่อนเข้า BUILD ไหม — ถ้า ok:
-   1. **fan-out agent หนึ่งตัวต่อหนึ่ง task แบบขนาน (read-only — ห้ามแก้โค้ด/ไฟล์ design)** — แต่ละตัวอ่าน task ทั้ง 4 ไฟล์ + `design.md`/`proposal.md` + โค้ดจริงที่เกี่ยว แล้ว "เดิน implement ในหัว" เพื่อหา:
-      - **blocker** — สิ่งที่ทำให้ implement ตาม spec ไม่ได้ (ขัดแย้งกับโค้ดจริง/กับ task อื่น, ข้อมูล/spec ขาด, dependency ผิด) — BUILD จะล้มถ้าไม่แก้
-      - **defer** — จุดที่ตัดสินใจ/ทำทีหลังได้ ไม่ block การเริ่ม BUILD แต่ต้องบันทึกและ track
-   2. task ไหนพบ issue → เขียน `tasks/<task>/issue.md` (template `.warnyin/template/stages/[topic]/tasks/[task-name]/issue.md`); ไม่พบ → ไม่ต้องสร้างไฟล์
-   3. รันครบทุก task แล้ว → **สรุปผลรวม** (จำนวน blocker/defer ต่อ task) ให้ user เห็นภาพ
-   4. **หาวิธีแก้ DESIGN ตาม issue** (แก้ `design.md` / task ที่กระทบ) โดย **ห้ามเดา ห้ามคิดขึ้นเอง** — ติดจริงๆ ให้สัมภาษณ์ user **ถามทีละข้อ + เสนอคำตอบแนะนำทุกครั้ง**; คำถามที่โค้ดตอบได้ → ไปอ่านโค้ดเอง
-   5. แก้แล้ว rerun dry-run เฉพาะ task ที่กระทบ วนจน **ไม่มี blocker ค้าง** (อัปเดตสถานะใน `issue.md` — defer ที่เหลือให้ user รับทราบ)
-11. **เสนอเข้า BUILD:** พร้อม implement ด้วย `/warnyin:build`
-
-> generate ไฟล์ task หลายใบพร้อมกันได้โดยใช้ sub-agent (เช่น fan-out หนึ่ง agent ต่อหนึ่ง task) — แต่ต้องผ่าน Gate ก่อนเสมอ
-> เครื่องที่ fan-out ขนานไม่ได้ (ไม่มี sub-agent tool) → dry-run สแกนทีละ task ตามลำดับด้วยหลักการเดียวกัน
-
----
-
-## 5. Output (สร้างที่ `docs/stages/<slug>/`)
-
-| ไฟล์ | เนื้อหา | optional? | template |
-|---|---|---|---|
-| `business.md` | what & why เชิงธุรกิจ (goal, persona, success metric) | ✅ ข้ามได้ถ้า change เล็ก | `.warnyin/template/stages/[topic]/business.md` |
-| `proposal.md` | what & why ของ change + ทางเลือก + scope | จำเป็น | `.warnyin/template/stages/[topic]/proposal.md` |
-| `design.md` | how — vertical slice, data model, contract, flow, **Spec delta** | จำเป็น | `.warnyin/template/stages/[topic]/design.md` |
-| `openapi.yaml` | API contract (OpenAPI 3.1) ของ topic ที่แตะ REST API | ✅ เฉพาะ topic ที่แตะ backend/REST API (`.warnyin/workflow/api-doc.md`) | — |
-| `tasks/<task-name>/spec.md` | spec เฉพาะ task (ดูข้อ 6) | จำเป็นต่อ task | `.warnyin/template/stages/[topic]/tasks/[task-name]/spec.md` |
-| `tasks/<task-name>/standard.md` | pattern โค้ด/shared component อิง techstack standard | จำเป็นต่อ task | `.warnyin/template/stages/[topic]/tasks/[task-name]/standard.md` |
-| `tasks/<task-name>/rule.md` | rule ที่ต้อง follow + rule ที่เสนอเพิ่ม (รอ SHIP) | จำเป็นต่อ task | `.warnyin/template/stages/[topic]/tasks/[task-name]/rule.md` |
-| `tasks/<task-name>/task.md` | รายละเอียด task + sub-tasks + dependency + acceptance | จำเป็นต่อ task | `.warnyin/template/stages/[topic]/tasks/[task-name]/task.md` |
-| `tasks/<task-name>/issue.md` | ผล dry-run: defer/blocker ที่พบ + แนวทางแก้ + สถานะ | ✅ เฉพาะเมื่อ dry-run แล้วพบ issue | `.warnyin/template/stages/[topic]/tasks/[task-name]/issue.md` |
-
----
-
-## 6. spec.md — กำหนด spec ตามชนิดของ task
-
-ใส่เฉพาะหัวข้อที่เกี่ยวกับ task นั้น:
-- **API task** → API SPEC ตามมาตรฐาน (endpoint, method, request/response schema, error, auth, status code)
-  - **★ adaptive API-doc:** ถ้า topic แตะ **backend/REST API จริง** (auto-detect ตาม `.warnyin/workflow/api-doc.md` §2) → ผลิต/อัปเดต `openapi.yaml` (OpenAPI 3.1) เป็น contract; `spec.md` **ชี้มาที่ `openapi.yaml`** ไม่เขียน schema ซ้ำ — ไม่ใช่ REST API → ข้าม
-- **UX/UI task** → UXUI SPEC (wireframe หรือ figma ref ถ้ามี), states, responsive
-- **data-flow** — ข้อมูลไหลจากไหนไปไหน
-- **user-flow** — ผู้ใช้เดินผ่านขั้นตอนไหน
-- **persona** — ทำเพื่อใคร
-- **test-flow** — จะทดสอบ/ยืนยันความถูกต้องยังไง
-
-## 7. ปรับความละเอียดตามขนาด change
-
-- **เล็ก** (fix bug นิดหน่อย): ข้าม `business.md`, `proposal.md`/`design.md` แบบสั้น, 1 task ก็พอ
-- **กลาง/ใหญ่**: ครบทุก artifact, แตก vertical slice หลาย task + sub-task, dependency ชัด
-
----
-
-## 8. Gate → เข้า BUILD (`/warnyin:build`) ได้เมื่อ
-
-- [ ] proposal.md (+ business.md ถ้าจำเป็น) + design.md ครบ และ user เห็นชอบ
-- [ ] **ไม่มีการเดา** — ทุกจุดที่ไม่ชัดถูกถาม (ทีละข้อ + recommended answer) และปิดแล้ว
-- [ ] design เป็น vertical slice ชัด — แต่ละ task/slice ส่งมอบคุณค่า end-to-end ได้
-- [ ] **Spec delta ครบ** — เทียบ `docs/features/<name>/spec.md` ของ feature ที่แตะ (ADDED/MODIFIED/REMOVED) หรือระบุ "ไม่มี delta"
-- [ ] **API contract (ถ้าแตะ REST API)** — topic ที่ auto-detect ว่าแตะ backend/REST API มี `openapi.yaml` (OpenAPI 3.1) ครบ + `spec.md` ของ API task ชี้มาที่ contract (ตาม `.warnyin/workflow/api-doc.md`); ไม่ใช่ REST API → ข้อนี้ N/A
-- [ ] ทุก task มี `spec.md` + `standard.md` + `rule.md` + `task.md` ครบ (ถ้ารัน node ได้: `node .warnyin/workflow/scripts/validate-topic.mjs <slug>` ควรไม่มี ✖ — เช็คโครง ไม่แทนการอ่าน semantic)
-- [ ] dependency / ลำดับระหว่าง task และ sub-task ชัดเจน เชื่อมต่อกัน
-- [ ] rule ที่ต้อง follow ถูกระบุครบ; rule/standard ใหม่ที่อยากเพิ่มถูก note ไว้ (รอ SHIP)
-- [ ] ถ้าทำ review panel: **blocker จากทุก role ถูกแก้/ปิดครบ** — สรุปผลบันทึกใน `design.md` section "Design review"
-- [ ] ถ้าทำ dry-run: **ไม่มี blocker ค้าง** — ทุก issue ถูกแก้/ปิดใน `issue.md`, defer ที่เหลือ user รับทราบแล้ว
-
-ยังไม่ครบ → ห้ามเขียนไฟล์ task / ห้ามโยน sub-agent / ห้ามข้ามไป BUILD
+# Stage: DESIGN
+
+> **Playbook กลาง — AI ทุกเจ้าทำตามไฟล์นี้ชุดเดียวกัน** (Claude Code / Codex / Antigravity / อื่นๆ)
+> เป้าหมาย: เสนอ **change ใหม่** พร้อมผลิต artifact ครบในขั้นเดียว — proposal (what & why) → design (how) → tasks (พร้อม execute)
+> **Context profile:** สวมโหมด `research` (`.warnyin/workflow/contexts/research.md`) ช่วงต้น (proposal/design) · `build` (`.warnyin/workflow/contexts/build.md`) ช่วงแตก task — session-level posture ของ stage นี้
+
+---
+
+## 1. DESIGN คืออะไร / ใช้เมื่อไหร่
+
+ใช้เมื่อ user อยากอธิบายสิ่งที่จะสร้าง/แก้แบบเร็วๆ แล้วได้ **ข้อเสนอที่สมบูรณ์** — มีทั้งการออกแบบ, spec, และ task ที่พร้อมลงมือทำ
+ครอบคลุม: build change, fix bug, แก้อะไรก็ตามที่เกี่ยวกับ **code / docs**
+
+- **ถ้าเป็นคำถาม หรือยังไม่มั่นใจเรื่อง design → แนะนำให้ใช้ `/warnyin:discovery` ก่อน** แล้วค่อยกลับมา DESIGN
+- ปรับความละเอียด artifact ตามขนาด change (ดูข้อ 7)
+
+---
+
+## 2. Input ที่ต้องอ่านก่อนเริ่ม
+
+1. `docs/project.md` — เป้าหมาย/ขอบเขตโปรเจกต์
+2. `docs/rule.md` + `docs/techstack/<component>/rule.md` — ★ กฎที่ต้อง follow
+3. `docs/techstack/<component>/standard.md` — ★ pattern/มาตรฐานการเขียนโค้ด
+4. `docs/techstack/<component>/{about,structure,test}.md`, `docs/codemap/index.md` — โครงสร้าง/วิธีเทสต์
+5. ถ้ามี Discovery → `docs/stages/<slug>/discovery.md`, `research.md`
+6. `docs/features/<name>/spec.md` — ★ behavior spec ปัจจุบันของ feature ที่ change แตะ (baseline สำหรับเขียน Spec delta; feature ยังไม่มี spec → ข้ามได้)
+7. โค้ดจริงที่เกี่ยวข้อง (inspect เพื่อตอบคำถามแทนการเดา)
+
+---
+
+## 3. หลักการทำงาน (operating principles)
+
+1. **ห้ามเดาเอง** — จุดที่ไม่มั่นใจ ให้ **ถามทีละข้อ + เสนอคำตอบที่แนะนำ (recommended answer) ทุกข้อ** (เหมือน Discovery) คำถามที่ตอบได้ด้วยโค้ด/เอกสาร → ไปอ่านเอง
+2. **Vertical slice architecture** — ออกแบบและแตก task เป็น "slice ที่ตัดผ่านทุก layer" (UI → API → domain → data → test) ทำงาน end-to-end ได้ในตัว **ไม่แบ่งตาม layer แนวนอน**
+   - **DAG-width toolkit (เทคนิคเสริม optional ลด serialization)** — คงนิยาม vertical slice เดิม (slice ตัดทุก layer end-to-end); toolkit เป็นเทคนิคเสริม เลือกตามเคส ไม่ใช่ข้อบังคับ — ใช้เมื่อแตก slice แล้วได้ dependency chain ลึก:
+     1. **Contract-first decouple** — เมื่อ task B ต้องการแค่ **interface/contract** ของ A (ไม่ใช่ runtime จริง) → ให้ B พึ่ง **contract artifact** (type/schema/openapi/ไฟล์กลางที่ตกลงใน design) แทน → A‖B ขนาน; integration พิสูจน์ที่ **full-gate** (`build.md` §3 ข้อ 8) — slice ยัง end-to-end แค่ stub ฝั่ง dependency ชั่วคราว
+     2. **Re-slice ต่างแกน** — ถ้าแตกตาม component-layer แล้วได้ chain → ลองแตกตาม **feature/capability ที่ independent** แทน
+     3. **ยอม serialize เฉพาะ chain แท้** — dependency ที่เลี่ยงไม่ได้ (foundation ต้องก่อน / doc ต้องอ้าง code) → ยอมรับ แล้วโฟกัส **ลดเวลา node บน critical path** (model tier + task-lean)
+3. **task = หน่วยที่โยนให้ sub-agent ได้** — แต่ละ task self-contained (มี spec + standard + rule ของตัวเอง) **กระชับพอ agent ทำจบ ไม่ฟุ่มเฟือย** (brief ยาวผิดปกติ → recheck dependency/re-slice) แต่ **เชื่อมต่อกัน** ผ่าน dependency/ลำดับที่ระบุชัด — เมื่อแตก task ต้อง **วาด DAG แล้ววัด critical-path depth (longest chain) + max wave width**: ถ้า DAG เป็น chain เส้นตรง (ทุก wave มี 1 task) ต้องมี **เหตุผล explicit** ว่าทำไม decouple ด้วย toolkit ข้อ 2 (3 เทคนิค) ไม่ได้ (กัน chain เผลอ)
+4. **สอดคล้องมาตรฐานเสมอ** — อิง rule + standard ของ techstack; ถ้าจะเพิ่ม rule/standard ใหม่ ให้ **note ไว้ก่อน** (ยังไม่แก้ไฟล์กลาง — รอ SHIP)
+5. **Gate ก่อนเขียนไฟล์ task จริง** — ต้องผ่านเกณฑ์ข้อ 8 ก่อนจะ generate ไฟล์ task และก่อนโยนให้ sub-agent
+6. **ใช้ role lens** — ออกแบบ (design.md) ด้วยมุม **SA** (`.warnyin/workflow/roles/sa.md`) และแตก/ตรวจ task ด้วยมุม **Tech Lead** (`.warnyin/workflow/roles/tech-lead.md`)
+7. **Review panel ก่อนแตก task (optional — ถาม user ก่อนเสมอ)** — ให้หลาย role (SA / Tech Lead / QA / Security / Infra ตาม `.warnyin/workflow/roles/`) รีวิว design ขนานแบบอิสระ (read-only) แล้วแก้ blocker ให้ครบก่อนแตก task (ดูขั้นตอนข้อ 4.6)
+8. **Dry-run ก่อนเข้า BUILD (optional — ถาม user ก่อนเสมอ)** — หลังเขียนไฟล์ task ครบ เสนอ user ว่าจะ dry-run ทั้งหมดเพื่อหาจุดบกพร่องไหม ถ้า ok → สแกนทุก task แบบขนาน (read-only) หา **defer/blocker** แล้วแก้ DESIGN จนไม่มี blocker ค้าง (ดูขั้นตอนข้อ 4.10) — การแก้ **ห้ามเดา ห้ามคิดขึ้นเอง**
+
+---
+
+## 4. ลำดับขั้นการทำงาน (process)
+
+1. **เตรียมพื้นที่:** ใช้/สร้างโฟลเดอร์ `docs/stages/<slug>/` (ถ้ามาจาก Discovery ใช้อันเดิม)
+2. **Ground + เคลียร์ความไม่ชัด:** อ่าน Input; ทุกจุดกำกวมเรื่อง design → ถามทีละข้อ + recommended answer จนชัด (ถ้าใหญ่/ไม่ชัดมาก → แนะนำ Discovery ก่อน)
+3. **business.md** *(optional — ข้ามได้ถ้า change เล็ก เช่น fix bug นิดหน่อย)*: what & why เชิงธุรกิจ — goal, คุณค่า, persona, success metric
+4. **proposal.md** (what & why): สรุป change ที่จะทำ, เหตุผล, ทางเลือกที่พิจารณา/ตัดทิ้ง, scope in/out
+5. **design.md** (how): ออกแบบเชิงเทคนิคแบบ vertical slice — slice มีอะไรบ้าง, แต่ละ slice ตัดผ่าน layer ไหน, data model, interface/contract, flow, ผลกระทบต่อระบบเดิม (ใช้ lens `.warnyin/workflow/roles/sa.md`) — **ครอบ "Spec delta" ด้วย**: เทียบพฤติกรรมที่ change นี้แตะกับ `docs/features/<name>/spec.md` ปัจจุบัน แล้วเขียน ADDED/MODIFIED/REMOVED (SHIP merge ตามนี้); change ไม่แตะพฤติกรรม feature → ระบุ "ไม่มี delta"
+6. **Review panel (optional — ถาม user ก่อน):** เสนอ user ว่าจะให้ panel หลาย role รีวิว design ก่อนแตก task ไหม — ถ้า ok:
+   1. fan-out sub-agent reviewer **ขนาน (read-only)** ตาม role card: **SA** (architecture/data model/contract), **Tech Lead** (feasibility/ขนาด task/dependency), **QA** (testability/acceptance), **Security** (ช่องโหว่/ข้อมูลอ่อนไหว), **Infra** (env/config/migration) — แต่ละตัวอ่าน `proposal.md` + `design.md` + โค้ดจริงที่เกี่ยว แล้วให้ความเห็นตาม checklist ใน `.warnyin/workflow/roles/<role>.md` แบ่งเป็น **blocker / suggestion**
+   2. รวมความเห็นทุก role → สรุปให้ user เห็นภาพ
+   3. **blocker → แก้ design ให้ครบ** โดยห้ามเดา — ติดจริงถาม user ทีละข้อ + เสนอคำตอบแนะนำ; suggestion → พิจารณา/บันทึกเหตุผลถ้าไม่ทำ
+   4. บันทึกสรุปผล panel + สิ่งที่แก้ ลงท้าย `design.md` (section "Design review")
+   5. เครื่องที่ fan-out ไม่ได้ → รีวิวทีละ role ด้วย checklist เดียวกัน
+7. **แตก tasks:** แปลง design เป็น task (= vertical slice / step ที่แก้); task ซับซ้อน → แตก **sub-task** ย่อย; **วาด DAG** + ระบุ **critical-path depth (longest chain) + max wave width + เหตุผลถ้า task ใดถูก serialize** — ถ้าได้ chain ลึก ลอง DAG-width toolkit (§3 ข้อ 2) ก่อนยอม serialize; เขียน **dependency graph / ลำดับ** ให้ sub-task เชื่อมกัน
+8. **rule check ต่อ task:** เปิด `docs/techstack/<component>/rule.md` หา rule ที่ task นี้ต้องโฟกัส → ใส่ใน `tasks/<task>/rule.md`; rule ใหม่ที่อยากเพิ่ม → note ใน section "เสนอเพิ่ม (รอ SHIP)"
+9. **เช็ค Gate (ข้อ 8)** → เมื่อผ่าน จึง **เขียนไฟล์ task ครบทุกใบ** (แตก task ด้วย lens `.warnyin/workflow/roles/tech-lead.md`)
+10. **Dry-run (optional — ถาม user ก่อน):** ถาม user ว่าต้องการ dry-run ทั้งหมดเพื่อหาจุดบกพร่องก่อนเข้า BUILD ไหม — ถ้า ok:
+   1. **fan-out agent หนึ่งตัวต่อหนึ่ง task แบบขนาน (read-only — ห้ามแก้โค้ด/ไฟล์ design)** — แต่ละตัวอ่าน task ทั้ง 4 ไฟล์ + `design.md`/`proposal.md` + โค้ดจริงที่เกี่ยว แล้ว "เดิน implement ในหัว" เพื่อหา:
+      - **blocker** — สิ่งที่ทำให้ implement ตาม spec ไม่ได้ (ขัดแย้งกับโค้ดจริง/กับ task อื่น, ข้อมูล/spec ขาด, dependency ผิด) — BUILD จะล้มถ้าไม่แก้
+      - **defer** — จุดที่ตัดสินใจ/ทำทีหลังได้ ไม่ block การเริ่ม BUILD แต่ต้องบันทึกและ track
+   2. task ไหนพบ issue → เขียน `tasks/<task>/issue.md` (template `.warnyin/template/stages/[topic]/tasks/[task-name]/issue.md`); ไม่พบ → ไม่ต้องสร้างไฟล์
+   3. รันครบทุก task แล้ว → **สรุปผลรวม** (จำนวน blocker/defer ต่อ task) ให้ user เห็นภาพ
+   4. **หาวิธีแก้ DESIGN ตาม issue** (แก้ `design.md` / task ที่กระทบ) โดย **ห้ามเดา ห้ามคิดขึ้นเอง** — ติดจริงๆ ให้สัมภาษณ์ user **ถามทีละข้อ + เสนอคำตอบแนะนำทุกครั้ง**; คำถามที่โค้ดตอบได้ → ไปอ่านโค้ดเอง
+   5. แก้แล้ว rerun dry-run เฉพาะ task ที่กระทบ วนจน **ไม่มี blocker ค้าง** (อัปเดตสถานะใน `issue.md` — defer ที่เหลือให้ user รับทราบ)
+11. **เสนอเข้า BUILD:** พร้อม implement ด้วย `/warnyin:build`
+
+> generate ไฟล์ task หลายใบพร้อมกันได้โดยใช้ sub-agent (เช่น fan-out หนึ่ง agent ต่อหนึ่ง task) — แต่ต้องผ่าน Gate ก่อนเสมอ
+> เครื่องที่ fan-out ขนานไม่ได้ (ไม่มี sub-agent tool) → dry-run สแกนทีละ task ตามลำดับด้วยหลักการเดียวกัน
+
+---
+
+## 5. Output (สร้างที่ `docs/stages/<slug>/`)
+
+| ไฟล์ | เนื้อหา | optional? | template |
+|---|---|---|---|
+| `business.md` | what & why เชิงธุรกิจ (goal, persona, success metric) | ✅ ข้ามได้ถ้า change เล็ก | `.warnyin/template/stages/[topic]/business.md` |
+| `proposal.md` | what & why ของ change + ทางเลือก + scope | จำเป็น | `.warnyin/template/stages/[topic]/proposal.md` |
+| `design.md` | how — vertical slice, data model, contract, flow, **Spec delta** | จำเป็น | `.warnyin/template/stages/[topic]/design.md` |
+| `openapi.yaml` | API contract (OpenAPI 3.1) ของ topic ที่แตะ REST API | ✅ เฉพาะ topic ที่แตะ backend/REST API (`.warnyin/workflow/api-doc.md`) | — |
+| `tasks/<task-name>/spec.md` | spec เฉพาะ task (ดูข้อ 6) | จำเป็นต่อ task | `.warnyin/template/stages/[topic]/tasks/[task-name]/spec.md` |
+| `tasks/<task-name>/standard.md` | pattern โค้ด/shared component อิง techstack standard | จำเป็นต่อ task | `.warnyin/template/stages/[topic]/tasks/[task-name]/standard.md` |
+| `tasks/<task-name>/rule.md` | rule ที่ต้อง follow + rule ที่เสนอเพิ่ม (รอ SHIP) | จำเป็นต่อ task | `.warnyin/template/stages/[topic]/tasks/[task-name]/rule.md` |
+| `tasks/<task-name>/task.md` | รายละเอียด task + sub-tasks + dependency + acceptance | จำเป็นต่อ task | `.warnyin/template/stages/[topic]/tasks/[task-name]/task.md` |
+| `tasks/<task-name>/issue.md` | ผล dry-run: defer/blocker ที่พบ + แนวทางแก้ + สถานะ | ✅ เฉพาะเมื่อ dry-run แล้วพบ issue | `.warnyin/template/stages/[topic]/tasks/[task-name]/issue.md` |
+
+---
+
+## 6. spec.md — กำหนด spec ตามชนิดของ task
+
+ใส่เฉพาะหัวข้อที่เกี่ยวกับ task นั้น:
+- **API task** → API SPEC ตามมาตรฐาน (endpoint, method, request/response schema, error, auth, status code)
+  - **★ adaptive API-doc:** ถ้า topic แตะ **backend/REST API จริง** (auto-detect ตาม `.warnyin/workflow/api-doc.md` §2) → ผลิต/อัปเดต `openapi.yaml` (OpenAPI 3.1) เป็น contract; `spec.md` **ชี้มาที่ `openapi.yaml`** ไม่เขียน schema ซ้ำ — ไม่ใช่ REST API → ข้าม
+- **UX/UI task** → UXUI SPEC (wireframe หรือ figma ref ถ้ามี), states, responsive
+- **data-flow** — ข้อมูลไหลจากไหนไปไหน
+- **user-flow** — ผู้ใช้เดินผ่านขั้นตอนไหน
+- **persona** — ทำเพื่อใคร
+- **test-flow** — จะทดสอบ/ยืนยันความถูกต้องยังไง
+
+## 7. ปรับความละเอียดตามขนาด change
+
+- **เล็ก** (fix bug นิดหน่อย): ข้าม `business.md`, `proposal.md`/`design.md` แบบสั้น, 1 task ก็พอ
+- **กลาง/ใหญ่**: ครบทุก artifact, แตก vertical slice หลาย task + sub-task, dependency ชัด
+
+---
+
+## 8. Gate → เข้า BUILD (`/warnyin:build`) ได้เมื่อ
+
+- [ ] proposal.md (+ business.md ถ้าจำเป็น) + design.md ครบ และ user เห็นชอบ
+- [ ] **ไม่มีการเดา** — ทุกจุดที่ไม่ชัดถูกถาม (ทีละข้อ + recommended answer) และปิดแล้ว
+- [ ] design เป็น vertical slice ชัด — แต่ละ task/slice ส่งมอบคุณค่า end-to-end ได้
+- [ ] **Spec delta ครบ** — เทียบ `docs/features/<name>/spec.md` ของ feature ที่แตะ (ADDED/MODIFIED/REMOVED) หรือระบุ "ไม่มี delta"
+- [ ] **API contract (ถ้าแตะ REST API)** — topic ที่ auto-detect ว่าแตะ backend/REST API มี `openapi.yaml` (OpenAPI 3.1) ครบ + `spec.md` ของ API task ชี้มาที่ contract (ตาม `.warnyin/workflow/api-doc.md`); ไม่ใช่ REST API → ข้อนี้ N/A
+- [ ] ทุก task มี `spec.md` + `standard.md` + `rule.md` + `task.md` ครบ (ถ้ารัน node ได้: `node .warnyin/workflow/scripts/validate-topic.mjs <slug>` ควรไม่มี ✖ — เช็คโครง ไม่แทนการอ่าน semantic)
+- [ ] dependency / ลำดับระหว่าง task และ sub-task ชัดเจน เชื่อมต่อกัน — **critical-path gate (judgment, ไม่ใช่ mechanical check):** ระบุ critical-path depth + max wave width; ถ้า DAG เป็น chain เส้นตรง (ทุก wave มี 1 task) → ต้องมี **เหตุผล explicit** ว่าทำไม decouple ด้วย DAG-width toolkit (§3 ข้อ 2) ไม่ได้ (กัน chain เผลอ)
+- [ ] rule ที่ต้อง follow ถูกระบุครบ; rule/standard ใหม่ที่อยากเพิ่มถูก note ไว้ (รอ SHIP)
+- [ ] ถ้าทำ review panel: **blocker จากทุก role ถูกแก้/ปิดครบ** — สรุปผลบันทึกใน `design.md` section "Design review"
+- [ ] ถ้าทำ dry-run: **ไม่มี blocker ค้าง** — ทุก issue ถูกแก้/ปิดใน `issue.md`, defer ที่เหลือ user รับทราบแล้ว
+
+ยังไม่ครบ → ห้ามเขียนไฟล์ task / ห้ามโยน sub-agent / ห้ามข้ามไป BUILD