@warnyin/agents 0.18.0 → 0.19.0

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

@@ -1,93 +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 ก่อนไหม — ไม่เดาเอง
+# 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/codemap.md

@@ -1,91 +1,91 @@
-# CODEMAP — สแกนโครงสร้างโปรเจกต์ + สร้าง architecture codemap แบบ token-lean
-
-> **Playbook กลาง — AI ทุกเจ้าทำตามไฟล์นี้ชุดเดียวกัน** (Claude Code / Codex / Antigravity / อื่นๆ)
-> เป้าหมาย: `docs/codemap/` ที่ **ประหยัด token** สำหรับให้ AI โหลดเข้า context — โครงสร้างระดับสูง ไม่ใช่ implementation detail
-
----
-
-## 1. ใช้เมื่อไหร่
-
-- หลังเพิ่ม feature ใหญ่ / refactor ครั้งสำคัญ
-- `/warnyin:init` ใช้ playbook นี้ตอนสร้าง codemap ครั้งแรก
-- **SHIP** ใช้ตอนขั้น "อัปเดต code map ทั้งหมด"
-
----
-
-## 2. ขั้นตอน
-
-### Step 1: สแกนโครงสร้างโปรเจกต์
-- ระบุชนิดโปรเจกต์: monorepo / single app / library / microservice
-- หา source directory ทั้งหมด (`src/`, `lib/`, `app/`, `packages/`, ...)
-- map entry points (`main.ts`, `index.ts`, `app.py`, `main.go`, ...)
-- สแกนขนานได้: fan-out sub-agent (read-only) ต่อ component/พื้นที่ — เครื่องที่ไม่มี sub-agent → ไล่ทีละส่วน
-
-### Step 2: สร้าง/อัปเดต codemap ใน `docs/codemap/`
-
-| ไฟล์ | เนื้อหา |
-|---|---|
-| `index.md` | สารบัญทั้งชุด + ภาพรวม component + จุดเข้า |
-| `architecture.md` | system diagram ระดับสูง, service boundary, data flow |
-| `backend.md` | API routes, middleware chain, service → repository mapping |
-| `frontend.md` | page tree, component hierarchy, state management flow |
-| `data.md` | ตาราง DB, relationship, migration history |
-| `dependencies.md` | external service, third-party integration, shared library |
-
-**สร้างเฉพาะไฟล์ที่ relevant** — โปรเจกต์ไม่มี frontend → ไม่ต้องมี `frontend.md`
-
-#### รูปแบบ codemap (token-lean)
-
-```markdown
-# Backend Architecture
-
-## Routes
-POST /api/users → UserController.create → UserService.create → UserRepo.insert
-GET  /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
-
-## Key Files
-src/services/user.ts (business logic, 120 lines)
-src/repos/user.ts (database access, 80 lines)
-
-## Dependencies
-- PostgreSQL (primary data store)
-- Redis (session cache, rate limiting)
-- Stripe (payment processing)
-```
-
-### Step 3: Diff detection
-- มี codemap เดิมอยู่ → คำนวณ % การเปลี่ยนแปลง
-- เปลี่ยน **> 30%** → แสดง diff + **ขอ user อนุมัติก่อนเขียนทับ**
-- เปลี่ยน **≤ 30%** → อัปเดต in place ได้เลย
-
-### Step 4: Metadata
-ใส่ freshness header บนสุดของทุกไฟล์:
-```html
-<!-- Generated: YYYY-MM-DD | Files scanned: N | Token estimate: ~X -->
-```
-
-### Step 5: Analysis report → `.reports/codemap-diff.txt`
-- ไฟล์ added / removed / modified ตั้งแต่สแกนครั้งล่าสุด
-- dependency ใหม่ที่ตรวจพบ
-- architecture changes (route ใหม่, service ใหม่ ฯลฯ)
-- คำเตือน staleness: doc ที่ไม่ถูกอัปเดต 90+ วัน
-
----
-
-## 3. หลักการ (tips)
-
-- โฟกัสโครงสร้างระดับสูง — **ไม่ใช่** implementation detail
-- ใช้ file path + function signature แทน code block เต็ม
-- แต่ละ codemap **< 1000 tokens** เพื่อโหลดเข้า context ได้ถูก
-- ใช้ ASCII diagram แทนคำบรรยาย data flow ยืดยาว
-- **ทุกอย่างต้องมาจากโค้ดจริง ณ วันสแกน — ห้ามเดา/ห้ามเขียนจากความจำ**
-
----
-
-## 4. Gate — จบเมื่อ
-
-- [ ] codemap ทุกไฟล์ตรงโค้ดจริง + มี freshness header
-- [ ] `index.md` ลิงก์ครบทุกไฟล์ codemap ที่มี
-- [ ] ทุกไฟล์ token-lean (< 1000 tokens)
-- [ ] diff > 30% ผ่านการอนุมัติจาก user แล้ว
-- [ ] `.reports/codemap-diff.txt` เขียนแล้ว
+# CODEMAP — สแกนโครงสร้างโปรเจกต์ + สร้าง architecture codemap แบบ token-lean
+
+> **Playbook กลาง — AI ทุกเจ้าทำตามไฟล์นี้ชุดเดียวกัน** (Claude Code / Codex / Antigravity / อื่นๆ)
+> เป้าหมาย: `docs/codemap/` ที่ **ประหยัด token** สำหรับให้ AI โหลดเข้า context — โครงสร้างระดับสูง ไม่ใช่ implementation detail
+
+---
+
+## 1. ใช้เมื่อไหร่
+
+- หลังเพิ่ม feature ใหญ่ / refactor ครั้งสำคัญ
+- `/warnyin:init` ใช้ playbook นี้ตอนสร้าง codemap ครั้งแรก
+- **SHIP** ใช้ตอนขั้น "อัปเดต code map ทั้งหมด"
+
+---
+
+## 2. ขั้นตอน
+
+### Step 1: สแกนโครงสร้างโปรเจกต์
+- ระบุชนิดโปรเจกต์: monorepo / single app / library / microservice
+- หา source directory ทั้งหมด (`src/`, `lib/`, `app/`, `packages/`, ...)
+- map entry points (`main.ts`, `index.ts`, `app.py`, `main.go`, ...)
+- สแกนขนานได้: fan-out sub-agent (read-only) ต่อ component/พื้นที่ — เครื่องที่ไม่มี sub-agent → ไล่ทีละส่วน
+
+### Step 2: สร้าง/อัปเดต codemap ใน `docs/codemap/`
+
+| ไฟล์ | เนื้อหา |
+|---|---|
+| `index.md` | สารบัญทั้งชุด + ภาพรวม component + จุดเข้า |
+| `architecture.md` | system diagram ระดับสูง, service boundary, data flow |
+| `backend.md` | API routes, middleware chain, service → repository mapping |
+| `frontend.md` | page tree, component hierarchy, state management flow |
+| `data.md` | ตาราง DB, relationship, migration history |
+| `dependencies.md` | external service, third-party integration, shared library |
+
+**สร้างเฉพาะไฟล์ที่ relevant** — โปรเจกต์ไม่มี frontend → ไม่ต้องมี `frontend.md`
+
+#### รูปแบบ codemap (token-lean)
+
+```markdown
+# Backend Architecture
+
+## Routes
+POST /api/users → UserController.create → UserService.create → UserRepo.insert
+GET  /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
+
+## Key Files
+src/services/user.ts (business logic, 120 lines)
+src/repos/user.ts (database access, 80 lines)
+
+## Dependencies
+- PostgreSQL (primary data store)
+- Redis (session cache, rate limiting)
+- Stripe (payment processing)
+```
+
+### Step 3: Diff detection
+- มี codemap เดิมอยู่ → คำนวณ % การเปลี่ยนแปลง
+- เปลี่ยน **> 30%** → แสดง diff + **ขอ user อนุมัติก่อนเขียนทับ**
+- เปลี่ยน **≤ 30%** → อัปเดต in place ได้เลย
+
+### Step 4: Metadata
+ใส่ freshness header บนสุดของทุกไฟล์:
+```html
+<!-- Generated: YYYY-MM-DD | Files scanned: N | Token estimate: ~X -->
+```
+
+### Step 5: Analysis report → `.reports/codemap-diff.txt`
+- ไฟล์ added / removed / modified ตั้งแต่สแกนครั้งล่าสุด
+- dependency ใหม่ที่ตรวจพบ
+- architecture changes (route ใหม่, service ใหม่ ฯลฯ)
+- คำเตือน staleness: doc ที่ไม่ถูกอัปเดต 90+ วัน
+
+---
+
+## 3. หลักการ (tips)
+
+- โฟกัสโครงสร้างระดับสูง — **ไม่ใช่** implementation detail
+- ใช้ file path + function signature แทน code block เต็ม
+- แต่ละ codemap **< 1000 tokens** เพื่อโหลดเข้า context ได้ถูก
+- ใช้ ASCII diagram แทนคำบรรยาย data flow ยืดยาว
+- **ทุกอย่างต้องมาจากโค้ดจริง ณ วันสแกน — ห้ามเดา/ห้ามเขียนจากความจำ**
+
+---
+
+## 4. Gate — จบเมื่อ
+
+- [ ] codemap ทุกไฟล์ตรงโค้ดจริง + มี freshness header
+- [ ] `index.md` ลิงก์ครบทุกไฟล์ codemap ที่มี
+- [ ] ทุกไฟล์ token-lean (< 1000 tokens)
+- [ ] diff > 30% ผ่านการอนุมัติจาก user แล้ว
+- [ ] `.reports/codemap-diff.txt` เขียนแล้ว

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

@@ -1,51 +1,51 @@
-# Contexts — context profile กลางของ workflow
-
-> **แก่นกลาง tool-agnostic** — context card แต่ละใบคือ "posture ของทั้ง session" ในโหมดหนึ่ง
-> AI ทุกเจ้าใช้ไฟล์ชุดเดียวกัน: อ่านตอนเริ่ม stage เพื่อ set โหมดของ session แล้วทำงานตาม playbook เดิม
-
-## หลักการ
-
-- **context = session-level posture** — วิธีคิด/ท่าทีรวมของ "ทั้ง session": ตอนนี้กำลังสำรวจ, กำลังสร้าง, หรือกำลังตรวจ
-- **role = task-level lens** ([`roles/`](../roles/README.md)) — มุมมอง/checklist ของ "หนึ่งบทบาทต่อหนึ่งงาน" (BA, Developer, QA, ...)
-- คนละมิติ ใช้คู่กันได้: เช่น session อยู่โหมด `build` (posture) + sub-agent สวม role `Developer` (lens ของงานนั้น)
-- context **ไม่ duplicate** checklist ของ stage playbook/role card — ชี้กลับ playbook เสมอ (single source of truth)
-
-## ตาราง context ↔ stage
-
-| Stage playbook | Context ที่เข้าคู่ | เหตุผล |
-|---|---|---|
-| [`discovery.md`](../stages/discovery.md) | `research` | สำรวจ/เข้าใจก่อนตัดสิน |
-| [`design.md`](../stages/design.md) | `research` + `build` | ต้น = research (propose), ปลาย = build (แตก task) |
-| [`build.md`](../stages/build.md) | `build` | ลงมือสร้าง vertical slice |
-| [`verify.md`](../stages/verify.md) | `review` | ตรวจ/ยืนยันด้วยการรันจริง |
-| [`ship.md`](../stages/ship.md) | `review` | ตรวจความครบก่อนส่งมอบ/promote |
-
-## วิธี activate (manual)
-
-- **AI หลัก:** ตอนเริ่ม stage → เปิด playbook stage นั้น เจอ callout "Context profile" ชี้มา → อ่าน context card → สวม posture แล้วทำงานตาม playbook
-- **User สั่งตรง:** บอกโหมดได้ชัดๆ เช่น "อยู่โหมด research" / "สวม build context" → AI อ่าน card ที่ตรง
-- playbook ทุก stage มี callout ชี้กลับมาที่ context ที่เข้าคู่ (reference graph วนกลับ ไม่ duplicate)
-
-## โครงของ context card ทุกใบ
-
-1. **Mindset** — วิธีคิดรวมของ session โหมดนี้ (2–4 บรรทัด)
-2. **Do / Don't** — bullet สั้น 2 ฝั่ง: ทำ vs ห้าม
-3. **Tool preference** — เครื่องมือที่ควรใช้ / เลี่ยง (read-only vs edit vs run) + **Model tier** (generic: deepest/balanced/cheap)
-4. **ใช้คู่ stage ไหน** — ชี้ playbook stage ที่เข้าคู่ (→ ลิงก์)
-
-> เพิ่ม context ใหม่ = เพิ่มไฟล์ที่นี่ + ใส่ callout ใน playbook stage ที่เข้าคู่ + อัปเดตตารางด้านบน
-> (เก็บให้บาง opinionated — 3 context พอ; อย่าให้ไหลเป็น catalog)
-
-## Model tier (generic — harness ตีเป็นรุ่นจริงเอง)
-
-แต่ละ context แนะนำ **model tier** ใน section "Tool preference" เพื่อคุม token/cost ตาม posture:
-
-| Context | Tier | งาน |
-|---|---|---|
-| `research` | `deepest reasoning` | สำรวจ / architecture / ตัดสินใจ trade-off |
-| `build` | `balanced` (worker เชิงกลไก → `cheap`) | implement vertical slice ตาม spec |
-| `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 ตามเดิม
+# Contexts — context profile กลางของ workflow
+
+> **แก่นกลาง tool-agnostic** — context card แต่ละใบคือ "posture ของทั้ง session" ในโหมดหนึ่ง
+> AI ทุกเจ้าใช้ไฟล์ชุดเดียวกัน: อ่านตอนเริ่ม stage เพื่อ set โหมดของ session แล้วทำงานตาม playbook เดิม
+
+## หลักการ
+
+- **context = session-level posture** — วิธีคิด/ท่าทีรวมของ "ทั้ง session": ตอนนี้กำลังสำรวจ, กำลังสร้าง, หรือกำลังตรวจ
+- **role = task-level lens** ([`roles/`](../roles/README.md)) — มุมมอง/checklist ของ "หนึ่งบทบาทต่อหนึ่งงาน" (BA, Developer, QA, ...)
+- คนละมิติ ใช้คู่กันได้: เช่น session อยู่โหมด `build` (posture) + sub-agent สวม role `Developer` (lens ของงานนั้น)
+- context **ไม่ duplicate** checklist ของ stage playbook/role card — ชี้กลับ playbook เสมอ (single source of truth)
+
+## ตาราง context ↔ stage
+
+| Stage playbook | Context ที่เข้าคู่ | เหตุผล |
+|---|---|---|
+| [`discovery.md`](../stages/discovery.md) | `research` | สำรวจ/เข้าใจก่อนตัดสิน |
+| [`design.md`](../stages/design.md) | `research` + `build` | ต้น = research (propose), ปลาย = build (แตก task) |
+| [`build.md`](../stages/build.md) | `build` | ลงมือสร้าง vertical slice |
+| [`verify.md`](../stages/verify.md) | `review` | ตรวจ/ยืนยันด้วยการรันจริง |
+| [`ship.md`](../stages/ship.md) | `review` | ตรวจความครบก่อนส่งมอบ/promote |
+
+## วิธี activate (manual)
+
+- **AI หลัก:** ตอนเริ่ม stage → เปิด playbook stage นั้น เจอ callout "Context profile" ชี้มา → อ่าน context card → สวม posture แล้วทำงานตาม playbook
+- **User สั่งตรง:** บอกโหมดได้ชัดๆ เช่น "อยู่โหมด research" / "สวม build context" → AI อ่าน card ที่ตรง
+- playbook ทุก stage มี callout ชี้กลับมาที่ context ที่เข้าคู่ (reference graph วนกลับ ไม่ duplicate)
+
+## โครงของ context card ทุกใบ
+
+1. **Mindset** — วิธีคิดรวมของ session โหมดนี้ (2–4 บรรทัด)
+2. **Do / Don't** — bullet สั้น 2 ฝั่ง: ทำ vs ห้าม
+3. **Tool preference** — เครื่องมือที่ควรใช้ / เลี่ยง (read-only vs edit vs run) + **Model tier** (generic: deepest/balanced/cheap)
+4. **ใช้คู่ stage ไหน** — ชี้ playbook stage ที่เข้าคู่ (→ ลิงก์)
+
+> เพิ่ม context ใหม่ = เพิ่มไฟล์ที่นี่ + ใส่ callout ใน playbook stage ที่เข้าคู่ + อัปเดตตารางด้านบน
+> (เก็บให้บาง opinionated — 3 context พอ; อย่าให้ไหลเป็น catalog)
+
+## Model tier (generic — harness ตีเป็นรุ่นจริงเอง)
+
+แต่ละ context แนะนำ **model tier** ใน section "Tool preference" เพื่อคุม token/cost ตาม posture:
+
+| Context | Tier | งาน |
+|---|---|---|
+| `research` | `deepest reasoning` | สำรวจ / architecture / ตัดสินใจ trade-off |
+| `build` | `balanced` (worker เชิงกลไก → `cheap`) | implement vertical slice ตาม spec |
+| `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

@@ -1,25 +1,26 @@
-# Context — build (โหมดลงมือสร้าง vertical slice)
-
-> session-level posture · playbook: `.warnyin/workflow/stages/*`
-
-## Mindset
-ส่งมอบ vertical slice ที่ทำงานจริง end-to-end — ทำตาม spec/standard/rule ของ task
-slice เล็กจบในตัว, "เขียว" ต้องเขียวจริงจากการรัน ไม่ใช่คาดว่าเขียว
-
-## Do / Don't
-- ✅ ทำตาม task spec ครบทุกข้อ ไม่เกิน/ไม่ต่ำ
-- ✅ อ่าน `troubleshooting.md` ก่อนแก้ error
-- ✅ reuse shared component ใน standard ก่อนเขียนใหม่
-- ✅ commit เล็ก โฟกัสทีละ slice
-- ❌ หลุด scope ของ task
-- ❌ เดา spec — กลับไปอ่าน design / ถาม
-- ❌ แก้ rule กลาง (note ไว้ รอ SHIP)
-
-## 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 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)
-- BUILD → [`stages/build.md`](../stages/build.md)
+# Context — build (โหมดลงมือสร้าง vertical slice)
+
+> session-level posture · playbook: `.warnyin/workflow/stages/*`
+
+## Mindset
+ส่งมอบ vertical slice ที่ทำงานจริง end-to-end — ทำตาม spec/standard/rule ของ task
+slice เล็กจบในตัว, "เขียว" ต้องเขียวจริงจากการรัน ไม่ใช่คาดว่าเขียว
+เขียนน้อยที่สุด: เดิน decision hierarchy (YAGNI→stdlib→native→dep→one-liner→ขั้นต่ำ) ก่อนเขียนทุกบรรทัด — ดู [`minimalism`](../minimalism.md)
+
+## Do / Don't
+- ✅ ทำตาม task spec ครบทุกข้อ ไม่เกิน/ไม่ต่ำ
+- ✅ อ่าน `troubleshooting.md` ก่อนแก้ error
+- ✅ reuse shared component ใน standard ก่อนเขียนใหม่
+- ✅ commit เล็ก โฟกัสทีละ slice
+- ❌ หลุด scope ของ task
+- ❌ เดา spec — กลับไปอ่าน design / ถาม
+- ❌ แก้ rule กลาง (note ไว้ รอ SHIP)
+
+## 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 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)
+- BUILD → [`stages/build.md`](../stages/build.md)

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

@@ -1,25 +1,25 @@
-# Context — research (โหมดสำรวจ/เข้าใจก่อนตัดสิน)
-
-> session-level posture · playbook: `.warnyin/workflow/stages/*`
-
-## Mindset
-เข้าใจก่อนตัดสิน — กว้างก่อนลึก ตั้งคำถาม > รีบสรุป
-สำรวจของจริง (โค้ด/เอกสาร) ไม่เดาจากความเคยชิน; สะสม evidence ให้พอก่อนเสนอทางเลือก
-
-## Do / Don't
-- ✅ อ่านโค้ด/เอกสารจริง ก่อนสรุปทุกครั้ง
-- ✅ ถามทีละข้อ + เสนอคำตอบให้ user ยืนยัน
-- ✅ บันทึก evidence (path/บรรทัด) ที่อ้างอิง
-- ❌ เดา/สรุปจากความเคยชินโดยไม่ยืนยัน
-- ❌ แก้ไฟล์ production ระหว่างสำรวจ
-- ❌ รีบสรุปก่อน scope ชัด
-
-## Tool preference
-- **ควรใช้:** read-only — Read / Grep / Glob / fast-context, `/warnyin:explore`
-- **เลี่ยง:** Edit / Write โค้ดจริง, คำสั่งที่เปลี่ยน state
-- **Model tier:** `deepest reasoning` — สำรวจ/architecture/ตัดสินใจ trade-off = งานคิดหนัก คุ้มใช้ตัวลึกสุด
-
-## ใช้คู่ stage ไหน
-- Discovery → [`stages/discovery.md`](../stages/discovery.md)
-- ช่วงต้น DESIGN (เก็บ context ก่อน propose) → [`stages/design.md`](../stages/design.md)
-- เช็คงานค้าง → [`next.md`](../next.md)
+# Context — research (โหมดสำรวจ/เข้าใจก่อนตัดสิน)
+
+> session-level posture · playbook: `.warnyin/workflow/stages/*`
+
+## Mindset
+เข้าใจก่อนตัดสิน — กว้างก่อนลึก ตั้งคำถาม > รีบสรุป
+สำรวจของจริง (โค้ด/เอกสาร) ไม่เดาจากความเคยชิน; สะสม evidence ให้พอก่อนเสนอทางเลือก
+
+## Do / Don't
+- ✅ อ่านโค้ด/เอกสารจริง ก่อนสรุปทุกครั้ง
+- ✅ ถามทีละข้อ + เสนอคำตอบให้ user ยืนยัน
+- ✅ บันทึก evidence (path/บรรทัด) ที่อ้างอิง
+- ❌ เดา/สรุปจากความเคยชินโดยไม่ยืนยัน
+- ❌ แก้ไฟล์ production ระหว่างสำรวจ
+- ❌ รีบสรุปก่อน scope ชัด
+
+## Tool preference
+- **ควรใช้:** read-only — Read / Grep / Glob / fast-context, `/warnyin:explore`
+- **เลี่ยง:** Edit / Write โค้ดจริง, คำสั่งที่เปลี่ยน state
+- **Model tier:** `deepest reasoning` — สำรวจ/architecture/ตัดสินใจ trade-off = งานคิดหนัก คุ้มใช้ตัวลึกสุด
+
+## ใช้คู่ stage ไหน
+- Discovery → [`stages/discovery.md`](../stages/discovery.md)
+- ช่วงต้น DESIGN (เก็บ context ก่อน propose) → [`stages/design.md`](../stages/design.md)
+- เช็คงานค้าง → [`next.md`](../next.md)