Roadmap: Phase 1–10

[monthop-gmail]

แผนพัฒนาทั้งหมดตาม §24 ของ direction doc
issue รายตัวอยู่ใน milestones

Phase	ขอบเขต	Issues	สถานะ
—	contract skeleton	—	✅ commit แรก
1	Foundation — storage, embedding, ingestion	#1 #2 #3 · #24	⬜
2	Retrieval — dense + FTS + JSONB + RRF	#4 #5 #6	⬜
3	Reranking — FlashRank + latency	#7	⬜
4	Service Boundary — knowledge.search	#8	⬜
5	Adapters — Direct/LCEL + FastMCP	#9 #10 #11	⬜
6	Evaluation — ground truth + metrics	#12 #13	⬜
7	Benchmark — 3 arms + p50/p95	#14	⬜
8	Security — tenant, ACL, policy	#15 #16	⬜
9	Integration — agent-platform	#17 · #25	🔵 คุยอยู่
10	Production Hardening	#18 #19 #20 #21	⬜

---

กฎที่ห้ามละเมิด (§25)

• ❌ ใส่ implementation ลง agent-platform
• ❌ ทำ MCP เป็น core
• ❌ retrieve แล้วค่อย filter ACL
• ❌ ให้ tenant filter เป็น optional ใน production path
• ❌ ผูก knowledge plane กับ vendor รายเดียว
• ❌ benchmark โดยไม่มี ground truth
• ❌ benchmark ที่ต้องยิง LLM ทุกครั้ง
• ❌ รวม generation latency กับ retrieval latency
• ❌ optimize HNSW ก่อนมี baseline
• ❌ สร้าง agent loop ใน repo นี้

ลำดับการ optimize (§26)

Correctness → Security → Evaluation → Baseline → Performance → Scale

Unauthorized retrieval = failure แม้ answer จะถูกต้อง

---

สิ่งที่ commit แรกทำไปแล้ว

เขียนจริงจนใช้ได้ (เพราะเป็น contract ไม่ใช่ implementation):
contracts.py · RRF fusion (§6) · ACL/tenant scope predicate (§4.2, §4.3) · stage-1 SQL + bind params
· provenance/citation · metrics · ground truth · service orchestration + latency breakdown

ตรวจจริงกับ PostgreSQL 16 + pgvector แล้ว: schema สร้างจาก clean DB ได้ และ stage-1 SQL ยิงได้จริง
โดย tenant / ACL / metadata filter กันได้ทั้งหมด

ที่ยังไม่ทำ raise NotImplementedError พร้อมระบุ phase — ไม่มี stub ที่คืนค่าปลอมเงียบ ๆ

เรื่องที่ทีมต้องตัดสินใจ (🔴 บล็อกของอื่นอยู่)

#5 — Thai full-text search · FTS ใช้ config english ตาม §8 ตรงตัว ถ้า corpus จริงเป็นไทย
sparse arm จะไม่ทำงาน และ RRF จะเหลือ dense ขาเดียวเงียบ ๆ ควรตัดสินใจก่อน Phase 2 จบ
เพราะเปลี่ยนทีหลัง = baseline เดิมใช้เทียบไม่ได้

#23 — workspace_id ✅ เคาะแล้ว 21 ส.ค. (ADR-0021)
ต้องมี workspace_id ตั้งแต่แรก · ไม่เท่ากับ tenant — tenant hard ที่ชั้นเก็บข้อมูล ข้ามไม่ได้ทุกกรณี ·
workspace deny-by-default ที่ชั้นตรวจสิทธิ์ ข้ามได้ถ้า policy อนุญาต แต่ต้องออก audit event ทุกครั้ง ·
department กลับไปเป็น label ของ workspace · งาน implement อยู่ที่ #24

ADR-0012 เกณฑ์ข้อ 2 — consumer รายที่สองของ knowledge/v1 คือใคร · ถามฝั่ง platform ไว้ใน #17 แล้ว
ยังไม่มีคำตอบ · งานขอ contract ใหม่เริ่มไม่ได้จนกว่าจะรู้

🔴 หนี้ที่ต้องเคลียร์: drift 27 วัน (#25)

repo นี้หยุดที่ 424e183 (21 ส.ค.) ส่วน agent-platform เดินไป 23 commits · ADR-0021 → ADR-0033
identity/v1 → v1.2.0 · policy/v1 → v1.4.0 · event/v1 → v1.7.1 · tool/v1 → v1.1.0 · error/v1 → v1.1.0

สองตัวที่กระทบโค้ดตรง ๆ: ADR-0031 (display_name เป็น PII ที่ไหลเข้า append-only — เราเพิ่ง add field นี้เอง)
และ ADR-0033 (resource ต้องพก scope — knowledge chunk คือ resource ตัวนั้น)

ความคืบหน้าจริง

• 424e183 — contracts.py เป็น projection ของ identity/v1 แล้ว (Principal.type / on_behalf_of),
  แก้ทิศทาง contract ที่บันทึกไว้ผิด, ล็อกคำศัพท์ actor/subject ตาม ADR-0017
• Phase 9: conform to the agent-platform contracts that exist, and earn knowledge/v1 #17 ปรับ scope แล้ว: จาก "อ่าน knowledge contract" (ซึ่งยังไม่มี) เป็น "conform กับ 6 contract ที่มีจริง
  แล้วสร้างหลักฐานเพื่อขอ knowledge/v1"
• 0604a2e — .mcp.json เข้า .gitignore (มี token และ repo นี้ public) พร้อม .mcp.json.example
• Decision: does the knowledge plane need workspace_id? ADR-0007 says department is a workspace label, not metadata #23 ปิดแล้ว → งานจริงอยู่ที่ Add workspace_id: deny-by-default scope at the authorization layer, not a second tenant #24 · เปิด Audit 27 days of upstream drift: ADR-0021 through ADR-0033, and pin the contract versions #25 สำหรับไล่ drift