@warnyin/agents 0.9.1 → 0.11.0

package/CHANGELOG.md

@@ -23,6 +23,16 @@
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-06-10
+
+### Added
+- **Build orchestration — BUILD เร็วขึ้นด้วย DAG กว้าง + model routing + lean verify** (feature `build-orchestration`) — แก้ root cause ที่ BUILD ช้า ("1 agent/wave, chain ยาว") โดยปรับ playbook 2 ชั้นแบบ **unify-in-place**: **(โครงสร้าง — DESIGN)** `src/.warnyin/workflow/stages/design.md` §3 เพิ่ม **DAG-width toolkit** (3 เทคนิคลด serialization: contract-first decouple / re-slice ต่างแกน / ยอม serialize เฉพาะ chain แท้ — toolkit optional คงนิยาม vertical slice เดิม) + **critical-path gate** (Gate §8 judgment: วัด critical-path depth + max wave width; chain เส้นตรงต้องมีเหตุผล explicit) + **task/context lean**; `roles/tech-lead.md` checklist + template `design.md` §7 (ช่อง depth/wave-width). **(กลไก — BUILD)** `src/.warnyin/workflow/scripts/build-wave.mjs` รับ `tasks: string[] | Array<{name, model?}>` — `model` per task แบบ **pass-through** เข้า `agent()` (ไม่ map/hardcode ชื่อรุ่น — payload generic); orchestrator `src/.claude/commands/warnyin/build.md` map tier→รุ่นจริง (Claude adapter); `stages/build.md` §3 ทำ **self-verify = scope component ตัวเอง** (integration เลื่อนไป full-gate ที่คง blocking). vocab tier generic `{cheap, balanced, deepest}` ใน `task.md` field `Model tier` (ไม่ระบุ = balanced; ไม่แตะ `balanced+` ของ review). **พิสูจน์เชิงประจักษ์:** งานอิสระ 4 task ขนาน 1 wave เทียบ chain 4 wave = **~3.95× เร็วขึ้น** (token เท่ากัน) + redesign DAG ของ scaffold-foundation chain depth 4 → wave width 2. **backward compatible** (`tasks: string[]` เดิม + ไม่ส่ง `model` → พฤติกรรมเดิม); payload ติดมากับ `--update` รอบถัดไป
+
+## [0.10.0] - 2026-06-09
+
+### Added
+- **Adaptive API documentation (OpenAPI 3.1) ตลอด lifecycle** — capability กลางใหม่ `.warnyin/workflow/api-doc.md`: stage **auto-detect** ว่า topic แตะ backend/REST API ไหม (techstack/route/annotation/API task/endpoint change) ถ้าใช่ → ผลิต+ยืนยัน+ส่งมอบ **OpenAPI 3.1 contract** ให้อัตโนมัติ (ไม่ใช่ REST API → ข้ามเงียบ ไม่ยัดเยียด). เสียบ hook บางๆ เข้า 3 stage โดย **ไม่ duplicate logic**: **DESIGN** ผลิต `docs/stages/<slug>/openapi.yaml` (design-first/code-first/hybrid) + `spec.md` ของ API task ชี้มาที่ contract; **VERIFY** ยืนยัน implementation จริงตรง contract (regen+diff หรือยิง request จริง — mismatch = ไม่ผ่าน เข้า fix loop); **SHIP** promote/merge → `docs/techstack/<component>/openapi.yaml` (living API contract). เพิ่มเกณฑ์ Gate ทั้ง 3 stage (N/A ถ้าไม่ใช่ REST API). ยึดหลัก **reference ไม่ vendor**: ชี้ skill `openapi-spec-generation` (`wshobson/agents`) เป็น template library + เครื่องมือ (Spectral/Redocly/OpenAPI Generator) แบบติดตั้งเอง — เพิ่มแถว SA/Developer ใน `roles/README.md` §"Skill เสริม". tool-agnostic (Codex/Antigravity ใช้ playbook ชุดเดียวกัน); payload ติดมากับ `--update` รอบถัดไป
+
 ## [0.9.1] - 2026-06-08
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warnyin/agents",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Warnyin Standard Workflow installer — 5-stage ways of work (Discovery/DESIGN/BUILD/VERIFY/SHIP) สำหรับทุกโปรเจกต์",
   "type": "module",
   "license": "MIT",

package/src/.claude/commands/warnyin/build.md

@@ -8,11 +8,12 @@ argument-hint: "[slug ของ topic]"
 0. **★ เช็ค context window ก่อนเริ่ม:** ถ้า context ของ session ถูกใช้ไปเยอะหรือ**เกินครึ่ง** → เสนอ user ให้ `/compact` หรือ `/clear` ก่อนเสมอ แล้วค่อยรัน `/warnyin:build <slug>` ใหม่ใน context ที่โล่ง (สถานะงานอยู่ในไฟล์ `docs/stages/<slug>/` ครบ) — อย่าเริ่ม fan-out ทั้งที่ context ใกล้เต็ม
 1. อ่าน `.warnyin/workflow/stages/build.md` ให้ครบก่อน แล้วทำตามทุกหลักการอย่างเคร่งครัด
 2. slug: $ARGUMENTS — ถ้าไม่ระบุให้ถามก่อน ว่าจะ build topic ไหน (ดูโฟลเดอร์ใน `docs/stages/`)
-3. **อ่าน task ทั้งหมด** ใน `docs/stages/<slug>/tasks/*/task.md` + `design.md` → ดึง dependency → สร้าง DAG → จัด **wave** ด้วย topological order
+3. **อ่าน task ทั้งหมด** ใน `docs/stages/<slug>/tasks/*/task.md` + `design.md` → ดึง dependency → สร้าง DAG → จัด **wave** ด้วย topological order · อ่าน field **`Model tier`** ของแต่ละ task ด้วย (generic `{cheap, balanced, deepest}`; ไม่มี = `balanced`) เพื่อใช้ map ตอนส่งเข้า build-wave (step 6)
 4. **Pre-check:** target เป็น git repo ไหม (จำเป็นสำหรับ worktree isolation) — ถ้าไม่ใช่ → fallback sequential shared-tree (`isolate:false`) และแจ้ง user. สร้าง build branch ใหม่ก่อนเริ่ม
 5. **ขออนุมัติครั้งเดียว** — ใช้ AskUserQuestion แสดง execution plan: แต่ละ wave มี task อะไร, อันไหน parallel, isolation mode, build branch → รอ go/no-go (อย่าเริ่มก่อนได้ไฟเขียว)
 6. **เดินทีละ wave** (หลังอนุมัติ):
-   - เรียก **Workflow** ด้วย `{ scriptPath: ".warnyin/workflow/scripts/build-wave.mjs", args: { slug, tasks: [<task ใน wave นี้>], isolate, baseRef: "<ชื่อ build branch ที่สร้าง step 4>" } }` — `baseRef` = build branch จริง (worktree fork จาก main → agent merge build branch เองก่อนทำงาน เพื่อเห็น `docs/stages/<slug>/` + output ของ wave ก่อนหน้า)
+   - **map tier→รุ่นจริง (Claude adapter):** สำหรับแต่ละ task ใน wave นี้ → อ่าน `Model tier` generic จาก `task.md` แล้ว map เป็นชื่อรุ่นจริงของ harness นี้: `cheap → claude-haiku-4-5` · `balanced → claude-sonnet-4-6` · `deepest → claude-opus-4-8` (ไม่ระบุ tier = `balanced`) — orchestrator เป็นคน map (payload `build-wave` คง generic ไม่ผูกชื่อรุ่น)
+   - เรียก **Workflow** ด้วย `{ scriptPath: ".warnyin/workflow/scripts/build-wave.mjs", args: { slug, tasks: [{ name: "<task ใน wave นี้>", model: "<ชื่อรุ่นจริงที่ map ได้>" }, ...], isolate, baseRef: "<ชื่อ build branch ที่สร้าง step 4>" } }` — `tasks` ส่งเป็น `{name, model}[]` (build-wave รับทั้ง `string[]` เดิมและ `{name, model?}[]`; `model` เป็น pass-through เข้า `agent()` ตรงๆ) · `baseRef` = build branch จริง (worktree fork จาก main → agent merge build branch เองก่อนทำงาน เพื่อเห็น `docs/stages/<slug>/` + output ของ wave ก่อนหน้า)
    - เมื่อ workflow คืนผล: ถ้า `isolate` → **integrate ด้วย `git checkout <result.branch> -- <ไฟล์ source ที่ task แก้>`** (checkout เฉพาะไฟล์ source ที่ scoped — เลี่ยง topic-docs copy ที่ agent merge เข้า worktree + ปลอด KB#11 tracked-deletion), แก้ conflict ถ้ามี; ถ้า shared-tree → review + commit ให้ · `task.md` status/checklist → main loop อัปเดตที่ main working dir ตอน integrate (E1 — agent แก้จาก worktree ไม่ได้ถ้า gitignored)
    - ถ้ามี task `failed` หรือ `skipped` → **หยุด** รายงาน user ก่อนไป wave ถัดไป
    - **รวม troubleshooting:** ดึงฟิลด์ `troubleshooting` จากผลของทุก agent ในรอบนี้ → เขียนรวมลง `docs/stages/<slug>/troubleshooting.md` (main loop เขียนเอง กันไฟล์ชนกันใน worktree)

package/src/.claude/commands/warnyin/design.md

@@ -14,6 +14,7 @@ argument-hint: "[slug ของ topic] [อธิบาย change สั้น
    - ระบุ slug → ใช้/สร้าง `docs/stages/<slug>/` (ถ้ามาจาก Discovery ใช้โฟลเดอร์เดิม)
    - ถ้าเป็นคำถาม/ยังไม่มั่นใจเรื่อง design → แนะนำ `/warnyin:discovery` ก่อน
 4. ผลิต artifact โดยใช้ template ใน `.warnyin/template/stages/[topic]/` เป็นโครง: `business.md` (ข้ามได้ถ้า change เล็ก), `proposal.md`, `design.md` (lens `.warnyin/workflow/roles/sa.md`), แล้วแตก `tasks/<task-name>/` (lens `.warnyin/workflow/roles/tech-lead.md`) แต่ละใบมี `spec.md` `standard.md` `rule.md` `task.md`
+   - **Model tier ต่อ task:** ตอนแตก task ระบุ field `Model tier` ใน `task.md` (generic `{cheap, balanced, deepest}`; ไม่ระบุ = `balanced`) — mechanical/scaffold/config → `cheap` · implement ตาม spec ปกติ → `balanced` · logic หนัก/security/algorithm/ไม่เคยทำ → `deepest` (BUILD orchestrator map tier→รุ่นจริงตอน fan-out — ดู `contexts/README.md` §"Model tier")
    - **Spec delta:** `design.md` ต้องครอบ section "9. Spec delta" — เทียบ `docs/features/<name>/spec.md` ปัจจุบัน (input ข้อ 6) แล้วเขียน ADDED/MODIFIED/REMOVED หรือ "ไม่มี delta" (กติกาเต็ม + gate ดู playbook §2/§4/§8 — ไม่ทำซ้ำที่นี่)
    - **Gate ดู playbook §8** — ถ้ารัน node ได้ validate `<slug>` ควรไม่มี ✖ (รายการเช็คอยู่ใน script + playbook ไม่ทำซ้ำที่นี่)
    - **Review panel (ถาม user ก่อน):** หลัง `design.md` เสร็จ ก่อนแตก task — ใช้ AskUserQuestion ถามว่าจะให้ panel รีวิวไหม ถ้า ok → fan-out subagent `warnyin-sa`, `warnyin-tech-lead`, `warnyin-qa`, `warnyin-security`, `warnyin-infra` (Agent tool, ขนาน, read-only) รีวิว proposal+design → รวมความเห็น สรุปให้ user → แก้ blocker ให้ครบ (ห้ามเดา) → บันทึก section "Design review" ท้าย `design.md`

package/src/.warnyin/template/stages/[topic]/design.md

@@ -31,13 +31,19 @@
 - จุดที่ต้องระวัง / backward compatibility:
 
 ## 7. Dependency ระหว่าง slice/task
-> slice/task เชื่อมกันยังไง ลำดับการทำ
+> slice/task เชื่อมกันยังไง ลำดับการทำ — วาด DAG แล้ววัด width (กัน chain เผลอ)
 
 ```
 task-1 ──▶ task-2 ──▶ task-3
               └──▶ task-4
 ```
 
+- **critical-path depth (longest chain):** <จำนวน wave ของ chain ที่ยาวที่สุด>
+- **max wave width:** <จำนวน task สูงสุดใน wave เดียว — >1 = ขนานได้>
+- **เหตุผลถ้า task ใดถูก serialize:** <ถ้า DAG เป็น chain เส้นตรง (ทุก wave 1 task) → ทำไม decouple ด้วย DAG-width toolkit (design.md §3 ข้อ 2) ไม่ได้>
+
+
+
 ## 8. Test strategy ระดับ design
 - จะยืนยันว่า design ทำงานถูกอย่างไร (ภาพรวม — รายละเอียดอยู่ใน task spec):
 

package/src/.warnyin/template/stages/[topic]/tasks/[task-name]/task.md

@@ -8,6 +8,7 @@
 | **Task** | `<kebab-case>` |
 | **Slice อ้างอิง** | `design.md` slice #__ |
 | **Component** | `admin-console` / `api-service` / ... |
+| **Model tier** | `cheap` / `balanced` / `deepest` _(optional; ไม่ระบุ = `balanced` — ดู `contexts/README.md` §"Model tier")_ |
 | **สถานะ** | `รอ build` / `กำลังทำ` / `เสร็จ` |
 
 ## 1. เป้าหมายของ task (vertical slice)

package/src/.warnyin/workflow/README.md

@@ -41,6 +41,7 @@ Discovery (optional) ──▶ DESIGN ──▶ BUILD ──▶ VERIFY ──▶
     codemap.md         #   playbook: CODEMAP — สแกน + สร้าง codemap แบบ token-lean
     explore.md         #   playbook: EXPLORE — สำรวจ/ตอบคำถามแบบ read-only ไม่สร้าง artifact
     next.md            #   playbook: NEXT — เช็คงานค้าง + แนะนำขั้นตอนถัดไป (read-only)
+    api-doc.md         #   capability: API-DOC — adaptive OpenAPI 3.1 contract (DESIGN/VERIFY/SHIP เรียกเอง)
     stages/            #   discovery ✅ · design ✅ · build ✅ · verify ✅ · ship ✅
     roles/             #   role card กลาง (task-level lens): ba, po, sa, tech-lead, developer, qa, security, infra
     contexts/          #   context profile กลาง (session-level posture): research, build, review + README

package/src/.warnyin/workflow/api-doc.md

@@ -0,0 +1,93 @@
+# API-DOC — เอกสาร REST API (OpenAPI 3.1) แบบ adaptive
+
+> **Playbook กลาง — AI ทุกเจ้าทำตามไฟล์นี้ชุดเดียวกัน** (Claude Code / Codex / Antigravity / อื่นๆ)
+> เป้าหมาย: ถ้า topic **แตะ backend/REST API จริง** → ผลิต + ยืนยัน + ส่งมอบ **OpenAPI 3.1 contract** ให้อัตโนมัติ ตลอด lifecycle (DESIGN → VERIFY → SHIP)
+
+---
+
+## 1. คืออะไร / ใช้เมื่อไหร่
+
+API-DOC ไม่ใช่ stage แยก และ **ไม่มี slash command** — เป็น **capability เสริมที่ stage เรียกใช้เอง** เมื่อ auto-detect พบว่า topic เกี่ยวกับ REST API
+
+- ทำงานเป็นส่วนหนึ่งของ DESIGN / VERIFY / SHIP — stage playbook ชี้มาที่ไฟล์นี้
+- **adaptive:** ตรวจ signal ทุก topic — ถ้า **ไม่ใช่** backend/REST API → **ข้ามทั้งหมดเงียบๆ** (ไม่ยัดเยียด ไม่สร้างไฟล์เปล่า)
+- tool-agnostic: เป็นมาตรฐาน OpenAPI 3.1 ล้วน ไม่ผูกกับ AI เจ้าใดหรือเฟรมเวิร์กใด
+
+---
+
+## 2. Auto-detect — topic นี้แตะ REST API ไหม?
+
+ดูสัญญาณต่อไปนี้ (เจอ **อย่างน้อยหนึ่ง** ที่ชัดเจน = ใช่):
+
+1. **techstack** — `docs/techstack/<component>/about.md` ระบุว่าเป็น backend/HTTP service / REST / web API
+2. **route ในโค้ด** — มี handler/controller ที่ผูก HTTP route เช่น Express/Fastify/NestJS/Koa/Hapi, FastAPI/Flask/Django REST, Spring/Gin/Echo, ASP.NET ฯลฯ
+3. **annotation/decorator** ที่ gen spec ได้อยู่แล้ว — tsoa, springdoc, drf-spectacular, FastAPI (Pydantic)
+4. **task ถูกจัดเป็น "API task"** ตอนแตก spec (design.md §6)
+5. **change เพิ่ม/แก้ HTTP endpoint** — request/response/error/auth/status code เปลี่ยน
+
+> สัญญาณคลุมเครือ (เช่น มีแค่ internal function ไม่ใช่ HTTP, RPC/gRPC ที่ไม่ใช่ REST, CLI/library ล้วน) → **ไม่ใช่** → ข้าม
+> ไม่แน่ใจจริง → ถาม user ทีละข้อ + เสนอคำตอบที่แนะนำ (ตามหลัก "ห้ามเดา" ของทุก stage)
+
+---
+
+## 3. เลือกโหมด (เลือกตาม signal + ระยะของงาน)
+
+| โหมด | เมื่อไหร่ | วิธี |
+|---|---|---|
+| **Design-first** | endpoint **ใหม่** ยังไม่มีโค้ด | เขียน `openapi.yaml` ก่อน (ตอน DESIGN) = contract ที่ BUILD จะ implement ตาม |
+| **Code-first** | API **มีอยู่แล้ว** + เฟรมเวิร์ก gen spec ได้ (FastAPI/tsoa ฯลฯ) | generate spec จากโค้ด แล้วตรวจ/เก็บเป็น artifact |
+| **Hybrid** | โค้ดมี annotation/decorator แต่ยังไม่ครบ | gen จาก annotation + เติม schema/example ที่ขาดด้วยมือ |
+
+โปรเจกต์เดียวกันใช้คนละโหมดต่อ topic ได้ — เลือกตามจริง
+
+---
+
+## 4. บทบาทต่อ stage
+
+### DESIGN — ผลิต contract
+- detect (ข้อ 2) → ถ้าใช่: ผลิต/อัปเดต `docs/stages/<slug>/openapi.yaml` (OpenAPI 3.1)
+  - endpoint ใหม่ → **design-first** เขียน contract ก่อน; API เดิม → **code-first/hybrid** gen จากโค้ดแล้วเติม
+- `tasks/<api-task>/spec.md` (API SPEC) **ชี้มาที่ `openapi.yaml`** — ไม่เขียน schema ซ้ำสองที่ (single source)
+- ถ้ามีเครื่องมือ lint ในโปรเจกต์ → รัน (ดูข้อ 5); ไม่มีก็ข้าม ไม่บังคับติดตั้ง
+
+### VERIFY — ยืนยันว่าโค้ดจริงตรง contract
+- topic มี `openapi.yaml` → **contract validation**: ยืนยันว่า implementation จริง = contract
+  - code-first: regen spec จากโค้ด → diff กับ `openapi.yaml` (ต้องไม่ต่าง)
+  - หรือยิง request จริงใน local env → ตรวจ response ตรง schema/status/error ที่ระบุ
+  - **★ runtime security:** การ regen (boot app จริง — FastAPI/tsoa) หรือยิง request จริง อยู่ใต้ runtime-security ของ `verify.md` §2 (local-only, scoped credential, no prod, no unnecessary egress) — ทบทวนก่อนปล่อย agent แตะของจริง
+- mismatch = **ไม่ผ่าน** → แก้ (โค้ด หรือ contract ตามต้นเหตุจริง) วนจนตรง — นับเป็นส่วนหนึ่งของ fix loop ใน verify.md §4
+
+### SHIP — promote contract ขึ้นเอกสารกลาง
+- ยก `openapi.yaml` → **`docs/techstack/<component>/openapi.yaml`** = living API contract ถาวร (เทียบเท่า `spec.md` ที่เป็น living behavior spec)
+- มี contract เดิมอยู่แล้ว → **merge ตาม delta** (เพิ่ม/แก้/ลบ path·schema ที่ topic แตะ) ไม่ทับทั้งไฟล์
+- อ้างถึงจาก `docs/features/<name>/spec.md` ของ feature ที่ใช้ endpoint นั้น
+
+---
+
+## 5. มาตรฐาน + เครื่องมือ (reference ไม่ vendor)
+
+- **มาตรฐาน:** OpenAPI **3.1.0** — `info`/`servers`/`paths`/`components.schemas`/`components.securitySchemes`; ใช้ `$ref` reuse, ใส่ `examples`, ระบุ error + status code + auth scheme ครบ, อย่า hardcode URL (ใช้ server variable)
+- **★ secret hygiene (บังคับ — `openapi.yaml` ถูก commit ถาวร):** ก่อน commit/promote ต้อง **scrub** — `servers.url` ใช้ placeholder/variable (ไม่ใช่ internal/staging host จริง), `examples`/`example`/default ใช้ค่า dummy (`user@example.com`, `<token>`) **ห้าม secret/credential/PII จริง**, `securitySchemes` ระบุแค่รูปแบบ ไม่ใส่ค่า token จริง — โดยเฉพาะตอน code-first gen จากโค้ด ที่ค่าจริงมักหลุดติดมา (สอด `docs/rule.md` §3.2 + spec convention "ค่าสังเคราะห์เท่านั้น")
+- **เครื่องมือ (ติดตั้งเองเมื่ออยากใช้ — ไม่ผูกใน workflow):**
+
+  | งาน | เครื่องมือ | คำสั่งตัวอย่าง |
+  |---|---|---|
+  | lint spec | Spectral | `spectral lint openapi.yaml` |
+  | lint/bundle/preview | Redocly CLI | `redocly lint openapi.yaml` |
+  | gen client SDK | OpenAPI Generator | `openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./gen/ts` |
+  | gen จากโค้ด | FastAPI (auto), tsoa (`@Route`/`@Get`) | ตามเฟรมเวิร์ก |
+
+- **Skill อ้างอิง (optional):** `openapi-spec-generation` — template library เต็ม (full API spec, FastAPI, tsoa, Spectral ruleset, SDK gen)
+  ที่มา: `wshobson/agents` → `plugins/documentation-generation/skills/openapi-spec-generation/`
+  (`SKILL.md` + `references/details.md` + `references/code-first-and-tooling.md`) — โปรเจกต์ไหนอยากได้ template สำเร็จรูปค่อยติดตั้ง
+
+---
+
+## 6. ที่อยู่ของ artifact
+
+| ระยะ | ที่ | หมายเหตุ |
+|---|---|---|
+| ระหว่างงาน | `docs/stages/<slug>/openapi.yaml` | optional — เฉพาะ topic ที่แตะ REST API |
+| ถาวร (หลัง SHIP) | `docs/techstack/<component>/openapi.yaml` | living API contract — SHIP merge ตาม delta |
+
+> **`<component>` resolution (ห้ามเดา):** topic แตะ **หลาย component** หรือ component ที่ **ยังไม่มีใน `docs/techstack/`** → ถาม user ว่าจะวาง contract ที่ component ไหน / สร้าง techstack entry ก่อนไหม — ไม่เดาเอง

package/src/.warnyin/workflow/contexts/README.md

@@ -47,3 +47,5 @@
 | `review` | `balanced+` | ตรวจ/จับ bug — ไม่ลด (พลาดแพงกว่า token) |
 
 > **tool-agnostic:** ใช้ vocab generic **ไม่ผูกชื่อรุ่น/ผลิตภัณฑ์ของ harness ใด ๆ** — แต่ละ harness map tier → รุ่นเอง (เทียบแนวทาง model selection ของ harness เช่นไฟล์ rules ฝั่ง performance); เป็น **guidance** ไม่ใช่ enforce
+
+> **per-task ใน BUILD (เพิ่มจาก per-context):** นอกจาก tier ระดับ context ด้านบน BUILD ยังกำหนด **model tier ต่อ task** ได้ผ่าน field `Model tier` ใน `task.md` — ใช้ subset `{cheap, balanced, deepest}` (ไม่ระบุ = `balanced` ตาม context build); mapping: mechanical/scaffold/config → `cheap` · implement ตาม spec ปกติ → `balanced` · logic หนัก/security/algorithm/ไม่เคยทำ → `deepest`. orchestrator ใน command (adapter) map tier→รุ่นจริง แล้วส่งเข้า `build-wave` per task — payload คง generic ตามเดิม

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

@@ -18,7 +18,7 @@ slice เล็กจบในตัว, "เขียว" ต้องเขี
 ## Tool preference
 - **ควรใช้:** Edit / Write / Bash, sub-agent fan-out, `build-wave`
 - **เลี่ยง:** แก้นอก scope task, แตะ rule/standard กลางใน `docs/`
-- **Model tier:** `balanced` (orchestrator/main loop ที่ตัดสินใจ integrate); **fan-out worker** ที่ทำ task ชัด/เชิงกลไกตาม spec → ลดเป็น `cheap` ได้ (คุม cost — งานกำหนดไว้แล้ว)
+- **Model tier:** `balanced` (orchestrator/main loop ที่ตัดสินใจ integrate); **fan-out worker per task** ตาม field `Model tier` ใน `task.md` (subset `{cheap, balanced, deepest}`; ไม่ระบุ = `balanced`): mechanical/scaffold/config → `cheap` · implement ตาม spec ปกติ → `balanced` · logic หนัก/security/algorithm/ไม่เคยทำ → `deepest` (คุม token/cost ต่อ agent — ดู `contexts/README.md` §"Model tier")
 
 ## ใช้คู่ stage ไหน
 - ปลาย DESIGN (แตก task) → [`stages/design.md`](../stages/design.md)

package/src/.warnyin/workflow/roles/README.md

@@ -43,4 +43,5 @@
 | QA | `browser-test` | `npx skills add ruvnet/ruflo@browser-test -g` |
 | Tech Lead | `/code-review` | Claude Code built-in |
 | Security | `/security-review` | Claude Code built-in |
+| SA, Developer | `openapi-spec-generation` | `wshobson/agents` → `plugins/documentation-generation/skills/openapi-spec-generation/` (template library — ใช้คู่ capability `.warnyin/workflow/api-doc.md`) · ⚠ third-party: ตรวจ `SKILL.md`/`references` ก่อนติดตั้ง + pin ที่ commit/tag (prompt-injection surface — `docs/rule.md` §3.2) |
 | BA, Infra | — | ยังไม่มี skill ภายนอกที่ผ่านเกณฑ์คุณภาพ (ใช้ role card พอ) |

package/src/.warnyin/workflow/roles/developer.md

@@ -19,6 +19,7 @@ implement vertical slice ที่รับมอบให้ **เสร็จ
 - [ ] เข้าใจไฟล์ก่อนแก้ (ใครใช้/contract/เจตนา) — ไม่แก้แบบไม่เข้าใจ (investigate-before-edit)
 - [ ] ไม่แก้ config/test ให้เขียวแทนแก้โค้ดจริง — config ผิดจริงแก้ได้ + เหตุผล + note (config-protection)
 - [ ] รัน test-flow ใน spec.md + build/lint **ผ่านจริง** — ห้ามรายงาน passed ทั้งที่ยังแดง
+- [ ] self-verify = **scope ตัวเองเท่านั้น** — test-flow ใน spec.md = unit + lint ของ **component ที่ task แตะ** ไม่ใช่ทั้ง repo; **ไม่รัน full cross-component build/integration/e2e ต่อ task** (integration cover ที่ full-gate หลัง merge ทุก wave — build.md §3 ข้อ 8 / §4 ข้อ 6)
 - [ ] ไม่ทิ้งขยะ: debug code, commented-out code, TODO ลอยๆ
 - [ ] เจอปัญหา → อ่าน `docs/troubleshooting.md` ก่อน; ปัญหายาก/ซ้ำที่แก้ได้ → รายงานในฟิลด์ troubleshooting
 - [ ] รายงานตรงความจริงทุกฟิลด์ — แก้ไม่ได้ให้ `failed` พร้อมเหตุผล ดีกว่า passed ปลอม

package/src/.warnyin/workflow/roles/tech-lead.md

@@ -12,9 +12,9 @@
 - reuse ก่อนเขียนใหม่เสมอ
 
 ## Checklist
-- [ ] แต่ละ task ขนาดพอเหมาะ: sub-agent ตัวเดียวทำจบ มี spec ครบในตัว ไม่ต้องเดา
+- [ ] แต่ละ task ขนาดพอเหมาะ: sub-agent ตัวเดียวทำจบ มี spec ครบในตัว **+ กระชับ; brief ยาวผิดปกติ → recheck dependency/re-slice** ไม่ต้องเดา
 - [ ] dependency graph ถูกต้อง ไม่มี cycle, ไม่มี dependency แอบแฝงที่ไม่ได้ระบุ (เช่น แก้ไฟล์เดียวกัน)
-- [ ] task ใน wave เดียวกัน parallel ได้จริง — ไม่ชนไฟล์/ตารางเดียวกัน
+- [ ] task ใน wave เดียวกัน parallel ได้จริง — ไม่ชนไฟล์/ตารางเดียวกัน **และ DAG ไม่ลึกเกินจำเป็น (ลอง DAG-width toolkit ก่อนยอม serialize — contract-first / re-slice ต่างแกน / serialize เฉพาะ chain แท้)**
 - [ ] จุดเสี่ยง technical (ของยาก/ไม่เคยทำ/พึ่งระบบนอก) ถูกระบุ + มีแผนรองรับ
 - [ ] ของเดิมที่ reuse ได้ถูกชี้ใน standard.md ของ task — ไม่ปล่อยให้ agent เขียนซ้ำ
 - [ ] effort สมเหตุผลกับคุณค่า — ถ้า task ใดแพงผิดปกติ ตั้งคำถามกับ design

package/src/.warnyin/workflow/scripts/build-wave.mjs

@@ -3,7 +3,10 @@
 //
 // args = {
 //   slug: string,            // ชื่อ topic เช่น "billing-redesign"
-//   tasks: string[],         // ชื่อ task ใน wave นี้ (โฟลเดอร์ docs/stages/<slug>/tasks/<task>)
+//   tasks: string[] | Array<{ name: string, model?: string }>,
+//                            // ชื่อ task ใน wave นี้ (โฟลเดอร์ docs/stages/<slug>/tasks/<task>)
+//                            // รับทั้ง string[] (เดิม, backward compat) และ {name, model?}[] — normalize ภายในเป็น {name, model}
+//                            // model = pass-through string (orchestrator map tier→รุ่นจริงก่อนส่งเข้ามา); script ไม่ map/ไม่ hardcode ชื่อรุ่น
 //   isolate?: boolean,       // true = worktree ต่อ task (ดีฟอลต์), false = shared tree (sequential)
 //   baseRef?: string,        // ชื่อ build branch เช่น "build/my-topic"; ไม่ส่ง = ไม่ sync (backward compat)
 // }
@@ -17,10 +20,29 @@ export const meta = {
 // บาง harness ส่ง args ของ Workflow เป็น string (JSON text) ไม่ใช่ object — รับทั้งสองแบบ
 const A = typeof args === 'string' ? JSON.parse(args) : (args || {})
 const slug = A.slug
-const tasks = A.tasks || []
 const isolate = !(A.isolate === false)
 const baseRef = A.baseRef || null   // ชื่อ build branch เช่น "build/my-topic"; ไม่ส่ง = ไม่ sync (backward compat)
 
+// normalize tasks: รับทั้ง string[] (เดิม) และ {name, model?}[] (ใหม่) → ภายในเป็น {name, model} เสมอ
+// string element → {name, model: undefined} (backward compat); model = pass-through string ไม่ map/ไม่ hardcode
+export function normalizeTasks(rawTasks) {
+  return (rawTasks || []).map((t) =>
+    typeof t === 'string' ? { name: t, model: undefined } : { name: t.name, model: t.model })
+}
+
+// สร้าง opts ของ agent() แบบ immutable — conditional spread: key หายเมื่อไม่มีค่า (ไม่ใช่ undefined)
+// แนวเดียวกับ baseRef เดิม (optional arg, conditional เฉพาะเมื่อมีค่า)
+export function buildOpts(task, isolate) {
+  return {
+    label: `build:${task.name}`,
+    schema: RESULT_SCHEMA,
+    ...(isolate && { isolation: 'worktree' }),
+    ...(task.model && { model: task.model }),
+  }
+}
+
+const tasks = normalizeTasks(A.tasks)
+
 if (!slug || tasks.length === 0) {
   log('ไม่มี slug หรือ tasks — ไม่มีอะไรให้ build')
   return { slug: slug || null, results: [], failed: [] }
@@ -109,16 +131,12 @@ function prompt(task) {
 }
 
 const results = await parallel(
-  tasks.map((task) => () =>
-    agent(prompt(task), isolate
-      ? { label: `build:${task}`, schema: RESULT_SCHEMA, isolation: 'worktree' }
-      : { label: `build:${task}`, schema: RESULT_SCHEMA })
-  )
+  tasks.map((task) => () => agent(prompt(task.name), buildOpts(task, isolate)))
 )
 
 const clean = results.filter(Boolean)
 const failed = clean.filter((r) => r.status === 'failed').map((r) => r.task)
-const skipped = tasks.filter((t) => !clean.some((r) => r.task === t))
+const skipped = tasks.filter((t) => !clean.some((r) => r.task === t.name)).map((t) => t.name)
 
 log(`เสร็จ ${clean.length}/${tasks.length} · ผ่าน ${clean.length - failed.length} · ล้ม ${failed.length}${skipped.length ? ` · ข้าม ${skipped.length}` : ''}`)
 

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

@@ -31,11 +31,11 @@ BUILD จะ **orchestrate การ implement** โดยกระจายง
 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` พร้อมเหตุผล **ห้ามรายงานผ่านทั้งที่ยังแดง**
+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 เสมอ** — หลัง merge ทุก wave แล้ว ต้องรัน build ทั้งหมด + test suite ทั้งหมด (รวม unit test) บน build branch ที่ integrate; **แก้วนจนเขียวหมด** ก่อนปิด BUILD (กันกรณี task รายเดี่ยวเขียวแต่พอรวมกันแล้วพัง)
+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 / อ่านโค้ดที่อ้างถึง ก่อนแก้)
@@ -57,7 +57,7 @@ BUILD จะ **orchestrate การ implement** โดยกระจายง
    - แต่ละ 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 ที่กระทบ
+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

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

@@ -32,7 +32,11 @@
 
 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/ลำดับที่ระบุชัด
+   - **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`)
@@ -54,7 +58,7 @@
    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 เชื่อมกัน
+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:
@@ -79,6 +83,7 @@
 | `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` |
@@ -91,6 +96,7 @@
 
 ใส่เฉพาะหัวข้อที่เกี่ยวกับ 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** — ผู้ใช้เดินผ่านขั้นตอนไหน
@@ -110,8 +116,9 @@
 - [ ] **ไม่มีการเดา** — ทุกจุดที่ไม่ชัดถูกถาม (ทีละข้อ + 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 ชัดเจน เชื่อมต่อกัน
+- [ ] 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 รับทราบแล้ว

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

@@ -50,7 +50,7 @@
 4. **★ Archive:** ย้ายทั้งโฟลเดอร์ → `docs/stages/achieved/<YYYY-MM-DD>-<slug>/` (ใช้ `git mv` ถ้าเป็น git repo)
 5. **อัปเดตเอกสารกลาง** (อ่านเนื้อหาจาก path ใน achieved):
    1. **`docs/features/<feature-name>/`** — feature ใหม่ → สร้างโฟลเดอร์ใหม่ (`feature.md` + `business.md`); ปรับปรุง feature เดิม → อัปเดตโฟลเดอร์เดิม โดยใช้เนื้อหาจาก `business.md` / `proposal.md` / `design.md` ของ topic — **และ merge `spec.md`** ตาม Spec delta ใน `design.md` §9: **ADDED** → ต่อท้าย `spec.md` · **MODIFIED** → แทนที่ requirement ชื่อตรงกัน (rename → หาด้วย `[เดิมชื่อ:]`) · **REMOVED** → ลบ requirement; **read-modify-verify — key ไม่เจอ → STOP:** MODIFIED/REMOVED ที่หา key ไม่เจอใน `spec.md` ของ feature ที่ `(→ feature:)` ระบุ → **หยุด ถาม user ห้าม merge เงียบ** (ห้ามตีความเป็น ADDED เอง); **feature ใหม่** → สร้าง `spec.md` จาก ADDED ทั้งก้อน (template `[feature-name]/spec.md`); **feature เดิมยังไม่มี `spec.md`** → สร้างใหม่จาก delta + พฤติกรรมจริง
-   2. **`docs/techstack/<component>/`** — `rule.md` / `standard.md` (learned-rule ที่ยืนยันแล้ว scope `component:<c>` + note "รอ SHIP" ใน tasks), `structure.md` (โครงสร้างที่เปลี่ยน), `test.md` (merge แผนเทสจาก `test.md` ของ topic)
+   2. **`docs/techstack/<component>/`** — `rule.md` / `standard.md` (learned-rule ที่ยืนยันแล้ว scope `component:<c>` + note "รอ SHIP" ใน tasks), `structure.md` (โครงสร้างที่เปลี่ยน), `test.md` (merge แผนเทสจาก `test.md` ของ topic); **`openapi.yaml` (ถ้า topic มี)** — promote `docs/stages/<slug>/openapi.yaml` → `docs/techstack/<component>/openapi.yaml` (living API contract): มีอยู่แล้ว → **merge ตาม delta** (path/schema ที่ topic แตะ) ไม่ทับทั้งไฟล์; ยังไม่มี → สร้างใหม่ — ทำตาม `.warnyin/workflow/api-doc.md` §4
    3. **`docs/rule.md`** — global rule ใหม่/ที่เปลี่ยน (learned-rule ที่ยืนยันแล้ว scope `project` — กฎระดับโปรเจกต์ ไม่ผูกกับ component เดียว)
    > promote learned-rule **เฉพาะตัวที่ user ยืนยัน (step 3)** ตาม scope: `component:<c>` → `docs/techstack/<c>/rule.md` · `project` → `docs/rule.md`
    4. **`docs/troubleshooting.md`** — merge entry จาก `troubleshooting.md` ของ topic (ปัญหา/อาการ/root cause/วิธีแก้/ป้องกันซ้ำ)
@@ -67,6 +67,7 @@
 |---|---|
 | `docs/features/<feature-name>/` | feature.md + business.md + spec.md (สร้างใหม่หรืออัปเดต — spec.md merge ตาม Spec delta) |
 | `docs/techstack/<component>/{rule,standard,structure,test}.md` | rule/standard ใหม่, โครงสร้าง, วิธีเทสที่ promote ขึ้น |
+| `docs/techstack/<component>/openapi.yaml` | living API contract — เฉพาะ topic ที่แตะ REST API (merge ตาม delta) |
 | `docs/rule.md` | global rule ที่เพิ่ม/เปลี่ยน |
 | `docs/troubleshooting.md` | KB ปัญหา-วิธีแก้ที่ merge เข้า |
 | `docs/infra.md`, `docs/project.md` | อัปเดตเฉพาะถ้ามีข้อมูลเกี่ยวข้อง |
@@ -83,6 +84,7 @@
 - [ ] learned-rules (planned + emergent) พิจารณาครบทุกตัว — note "รอ SHIP" ใน `tasks/*/rule.md` + `standard.md` + บทเรียน emergent จาก build/verify/troubleshooting; ทุก promote มี **evidence + user ยืนยัน**, ตัดทิ้งมีเหตุผล
 - [ ] `docs/troubleshooting.md` รวม entry จาก topic แล้ว
 - [ ] `docs/techstack/`, `docs/rule.md`, `docs/infra.md`, `docs/project.md` อัปเดตตามที่เกี่ยวข้อง
+- [ ] **API contract (ถ้า topic มี `openapi.yaml`)** — promote/merge เข้า `docs/techstack/<component>/openapi.yaml` ตาม delta แล้ว (`.warnyin/workflow/api-doc.md`)
 - [ ] `docs/codemap/` ตรงกับโค้ดจริงปัจจุบัน
 - [ ] `ship.md` สรุปการส่งมอบเขียนครบใน achieved
 - [ ] user รับทราบผลการส่งมอบ

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

@@ -18,6 +18,7 @@
 1. **spec + tasks ทั้งหมด** — `docs/stages/<slug>/tasks/*/spec.md` + `task.md`, `design.md`, `proposal.md`
    → เข้าใจ **จุดประสงค์ของ topic** และสิ่งที่ต้องยืนยัน (อย่าเทสผ่านๆ โดยไม่เข้าใจ)
 2. **`docs/features/<name>/spec.md` = regression baseline** — อ่าน behavior spec ของ feature ที่ topic แตะ (ดูจาก Spec delta ใน `design.md`); topic แตะหลาย feature → baseline = union ของ spec ทุก feature ที่ delta อ้างถึง; feature ยังไม่มี spec → ข้ามได้ (วิธีเดิม)
+   - **`docs/stages/<slug>/openapi.yaml` (ถ้ามี)** = API contract ที่ต้องยืนยัน — topic ที่แตะ REST API ต้อง verify ว่าโค้ดจริง **ตรง contract** (ดูข้อ 4)
 3. **`docs/techstack/<component>/test.md`** — guideline ว่าเทสยังไง (เช่น frontend: e2e smoke ผ่าน **playwright-cli**)
    → ถ้า **ไม่มี** guideline → แนะนำว่าควรเทสแบบไหน/วิธีใดได้บ้าง แล้วเขียนแผนลง `test.md`
 4. **`docs/infra.md`** — local env / service ที่ต้องรันเพื่อเทส
@@ -49,6 +50,7 @@
 2. **วางแผนเทส → เขียน `test.md`:** ตาม guideline `docs/techstack/<component>/test.md`; ไม่มีก็เสนอวิธี (e2e smoke / integration / manual ฯลฯ) แล้วเขียนแผน — **ครอบทั้ง regression (scenario เดิมใน baseline) + test case ใหม่ (scenario ใน Spec delta)**
 3. **เตรียม local env:** รัน service ที่เกี่ยวข้องตาม `infra.md`
 4. **รันเทสตามแผน:** functional ตาม test-flow ใน spec; FE → e2e smoke (playwright-cli) + ตรวจ UX/UI
+   - **★ contract validation (ถ้ามี `openapi.yaml`):** ยืนยัน implementation จริง = contract ตาม `.warnyin/workflow/api-doc.md` §4 (code-first regen → diff, หรือยิง request จริง → ตรวจ response/status/error ตรง schema); mismatch = ไม่ผ่าน → เข้า fix loop ข้อ 5
 5. **ไม่ผ่าน → แก้ → rerun:** วนจนผ่าน **นับจำนวนรอบ/จำนวนแก้**; ปัญหายาก→`troubleshooting.md`; ถ้านานเกิน→ถาม user (ทีละข้อ + recommended)
 6. **เขียนสรุป `verify.md`:** ผลเทส + รายการแก้ไข + **จำนวนการแก้ไข** + ผล UX/UI
 7. **ปิดงาน:** เสนอเข้า SHIP ด้วย `/warnyin:ship`
@@ -70,6 +72,7 @@
 - [ ] เทสตาม **จุดประสงค์ของ topic** ครบ (functional ตาม test-flow ใน spec)
 - [ ] **regression ตาม baseline** — scenario เดิมใน `docs/features/<name>/spec.md` ของ feature ที่แตะ ยังผ่าน (ยกเว้นที่ MODIFIED/REMOVED) + scenario ใน Spec delta ผ่าน
 - [ ] Frontend: **UX/UI verify ผ่าน**
+- [ ] **API contract (ถ้ามี `openapi.yaml`)** — implementation จริงตรง contract (path/schema/status/error/auth); mismatch ถูกแก้จนตรง (ตาม `.warnyin/workflow/api-doc.md`)
 - [ ] ทุกข้อที่ไม่ผ่านถูกแก้จน **verify ผ่านหมด**
 - [ ] `test.md` (แผน) + `verify.md` (สรุป + จำนวนการแก้ไข) เขียนครบ
 - [ ] ปัญหายาก/ซ้ำถูกบันทึก `troubleshooting.md`