approval/v1: guarantee บังคับให้ "อ้างใบเดิม" แต่ schema ไม่มี field ให้ · และ REQUIRE_CHANGES ไม่มีปลายทาง

[monthop-gmail]

พบระหว่างลงมือทำ devfactory-core#5
(Governance Decision Interface) — ฝั่งเราจะ implement ตาม approval/v1 แล้วพบว่ามี guarantee
ข้อหนึ่งที่ schema ไม่มี field ให้ทำตาม

ช่องว่าง

contracts/approval/v1/approval.schema.yaml · บล็อก guarantees (🔒 frozen) ข้อแรก:

"decision เป็น immutable — แก้ไม่ได้หลังบันทึก · การเปลี่ยนใจคือ approval ใบใหม่ที่อ้างใบเดิม"

แต่ใน properties ไม่มี field ไหนให้ "อ้างใบเดิม" ได้เลย — ไล่ครบทุกตัวแล้ว
(approval_id tenant_id workspace_id subject execution_id agent_id decision reason
authority decided_at policy_id action_risk expires_at escalation_target)
· grep -rn supersede contracts/ ทั้งโฟลเดอร์ได้ 0 ผลลัพธ์

ผลคือ consumer ที่ทำตาม guarantee นี้จะเขียน approval ใบใหม่ที่ ไม่มีทางบอกได้ว่ามันแทนใบไหน
ห่วงโซ่การเปลี่ยนใจจึงขาดใน audit trail ทั้งที่ guarantee บังคับให้มีอยู่

เสนอ

เพิ่ม property ที่ไม่บังคับ:

  supersedes_approval_id:
    $ref: https://schemas.agent-platform.internal/identity/v1/identity.schema.yaml#/$defs/Id
    description: >-
      approval ใบที่ใบนี้มาแทน — ต้องมีเมื่อเป็นการเปลี่ยนใจ (ดู guarantee ข้อแรก)
      ใบเดิมยังคงอยู่และห้ามแก้ · ห่วงโซ่นี้คือหลักฐานว่าใครเปลี่ยนใจเมื่อไหร่

เป็นการ เพิ่ม optional property ไม่แตะ required ไม่แตะบล็อก guarantees ที่ frozen ไว้
· ตามที่ contract-semantics.yaml ฝั่งเราเขียนไว้ นี่อยู่ในกลุ่ม platform_may_add_freely
ซึ่งทำผ่าน ADR ฝั่งท่านได้เลย ไม่ต้องมี RFC ที่ devfactory-core

ระหว่างนี้ฝั่งเราทำอะไรไปก่อน

ใส่ supersedes_decision_id ใน payload ของเราเอง (schema ไม่ได้ปิด additionalProperties)
พร้อมคอมเมนต์กำกับว่าเป็นการเติมช่องที่สัญญายังไม่มี — ถ้าท่านรับข้อเสนอนี้ เราจะเปลี่ยนไปใช้ชื่อ
ที่ท่านกำหนดแทนทันที ขอชื่อที่จะใช้จริงด้วยครับ จะได้ไม่ต้อง migrate สองรอบ

---

เรื่องที่สอง — REQUIRE_CHANGES ไม่มีใครบอกว่าไปสถานะไหน

พ่วงมาในอิชูเดียวกันเพราะมาจากงานเดียวกันและกระทบ approval/v1 ตัวเดียวกัน

guarantee ข้อสี่ (🔒 frozen) บอกว่า:

"REQUIRE_CHANGES ไม่ใช่ REJECT — งานยังมีชีวิตและกลับมายื่นใหม่ได้"

ซึ่งบอกชัดว่ามัน ไม่ใช่อะไร แต่ไม่มีที่ไหนบอกว่ามัน คืออะไร ในเชิง lifecycle
· ผมไล่ฝั่งท่านแล้ว REQUIRE_CHANGES ปรากฏใน approval.schema.yaml (enum + guarantee),
decisions/0006, decisions/0010, planes/policy.md — ทุกที่พูดถึงมันในฐานะ vocabulary
ของคำตัดสิน ไม่มีที่ไหนผูกกับสถานะของงาน

ฝั่ง devfactory-core state machine ปัจจุบัน GOVERNANCE_ANALYSIS มีทางออกแค่
APPROVED กับ REJECTED เท่านั้น — REQUIRE_CHANGES จึงไม่มีปลายทางให้ลง

เรารู้ว่าการเลือกปลายทางเป็นของเรา (บล็อก guarantees ระบุว่า frozen เพราะเป็นของ
devfactory-core RFC-0002) และจะทำเป็น RFC ที่ repo เรา · ที่ถามคือ ก่อนเราเคาะ
มีอะไรฝั่งท่านที่สมมติพฤติกรรมบางอย่างไว้แล้วหรือเปล่า จะได้ไม่เลือกทางที่ทำสัญญาอื่นพัง

ทางเลือกที่เราเห็นตอนนี้:

	ทาง	ผลต่อสัญญา
ก	เพิ่ม edge GOVERNANCE_ANALYSIS → DRAFT	ตรงกับ "งานยังมีชีวิตและกลับมายื่นใหม่ได้" มากที่สุด · ไม่เพิ่ม vocabulary ใหม่
ข	ใช้ทาง REJECTED → DRAFT เดิม	❌ ขัด guarantee ข้อสี่ตรง ๆ ตัดทิ้ง
ค	เพิ่ม state ที่ 14 (เช่น CHANGES_REQUESTED)	ชัดที่สุดใน audit trail แต่เป็น vocabulary ใหม่ที่ท่านต้องรับรู้ด้วย (RFC-0009)

ระหว่างที่ยังไม่เคาะ ฝั่งเราจะไม่เดา — engine จะรับ REQUIRE_CHANGES เป็นค่าที่ถูกต้อง
ตาม vocabulary แต่ ปฏิเสธการใช้งานด้วย error เฉพาะ ที่ชี้กลับมาที่คำถามนี้
ดีกว่าปล่อยให้โค้ดเลือกกฎ lifecycle เอง แล้วเอกสารตามไม่ทัน — ซึ่งเป็นเรื่องที่เพิ่งเกิดกับเราใน
#14 มาแล้วรอบหนึ่ง

[monthop-gmail]

ครึ่งหลังของอิชูนี้ปิดแล้ว — REQUIRE_CHANGES มีปลายทางแล้ว

เราถามไว้ว่ามีอะไรฝั่งท่านที่สมมติพฤติกรรมของ REQUIRE_CHANGES ไว้หรือเปล่า คำตอบคือไม่มี
— ไล่แล้วมันปรากฏใน approval.schema.yaml (enum + guarantee), decisions/0006,
decisions/0010, planes/policy.md และทุกที่พูดถึงมันในฐานะ vocabulary ของคำตัดสิน
ไม่มีที่ไหนผูกกับสถานะของงาน

เราจึงตัดสินที่ฝั่งเราตามที่บอกไว้ — RFC-0011
(PR #22 merged):

REQUIRE_CHANGES → GOVERNANCE_ANALYSIS → DRAFT (เพิ่ม edge ใหม่ในตาราง transition)

ทำไมทางนี้ และทำไมไม่กระทบสัญญาของท่าน

• ตรงกับ guarantee ที่ท่าน frozen ไว้ที่สุด — "ไม่ใช่ REJECT · งานยังมีชีวิตและกลับมายื่นใหม่ได้"
• ไม่เพิ่ม vocabulary ใหม่ จึงไม่เข้าเงื่อนไข RFC-0009 และไม่ต้องมี ADR ฝั่งท่าน
  · ทางเลือกที่เราตัดทิ้งคือการเพิ่ม state ที่ 14 (CHANGES_REQUESTED) ซึ่งจะลากท่านเข้ามาเกี่ยว
• guarantee ยังคงอยู่จริง ไม่ใช่แค่ในคำพูด เพราะ สองเคสแยกออกจากกันด้วยเส้นทาง:

REJECT           GOVERNANCE_ANALYSIS → REJECTED → DRAFT     ← REJECTED อยู่ใน history
REQUIRE_CHANGES  GOVERNANCE_ANALYSIS → DRAFT                ← ข้าม REJECTED

อ่านย้อนจาก audit trail แยกได้โดยไม่ต้องเปิด decision record · มี conformance check
ที่ replay ทั้งสอง flow แล้วพิสูจน์ว่าเส้นทางต่างกันจริง

ผลข้างเคียงที่อยากให้รู้ไว้ (ไม่ต้องทำอะไร)

decision: REQUIRE_CHANGES ถูกผลิตออกมาจริงแล้วและ validate กับ approval/v1 ผ่าน
· ก่อนหน้านี้ engine ของเราปฏิเสธค่านี้อยู่ ทำให้หนึ่งในสามของ vocabulary ไม่เคยถูกใช้เลย

---

อิชูนี้จึงเหลือแค่ครึ่งแรก — supersedes_approval_id ซึ่งเป็นของฝั่งท่าน
กำลังทำอยู่ครับ จะส่งมาให้ดูเร็ว ๆ นี้

[monthop-gmail]

ปิดอิชู — จบทั้งสองครึ่งแล้ว

ครึ่งแรก · supersedes_approval_id — PR #24
merged (3a01ab9) · approval/v1 v1.1.0 มี optional field นี้แล้ว
· ADR-0013 บันทึกเหตุผลว่าทำไมเป็นของ platform, ทำไม optional, และทำไมไม่ bump major
(ADR-0006 เขียน "เพิ่ม optional field" ไว้ในลิสต์ ไม่ breaking ตรง ๆ)
· drift_check 19 passed · 0 fail

ครึ่งหลัง · REQUIRE_CHANGES — ตอบไปแล้วในคอมเมนต์ก่อนหน้า
· ไม่มีอะไรฝั่งนี้สมมติพฤติกรรมไว้ devfactory-core จึงตัดสินเองด้วย
RFC-0011
→ GOVERNANCE_ANALYSIS → DRAFT · ไม่เพิ่ม vocabulary ใหม่ จึงไม่ต้องทำอะไรที่ repo นี้

ฝั่ง consumer เปลี่ยนตามแล้ว

devfactory-core bump pin มาที่ 3a01ab9
(#23 — แยก PR ตามกฎของเขาที่ห้าม
อัปเกรด pin ปนกับงาน code) แล้ว rename payload key จากชื่อชั่วคราว supersedes_decision_id
เป็น supersedes_approval_id ตามสัญญา (#24)

ไม่มี payload ชื่อเก่าตกค้าง — เปลี่ยนภายในไม่กี่ชั่วโมงหลัง field จริงออก

บันทึกไว้สองข้อ เผื่อรอบหน้า

1. drift_check ตรวจช่องว่างแบบที่อิชูนี้เจอไม่ได้ — check_frozen เทียบแค่ vocabulary
กับ จำนวน guarantee ตรวจไม่ได้ว่า guarantee แต่ละข้อมี field รองรับไหม
· อิชูนี้จึงต้องเจอด้วยคนที่ implement จริง และ จะเจอแบบเดิมอีกถ้ามี guarantee ใหม่ที่ต้องการ field
· บันทึกไว้ใน Consequences ของ ADR-0013 แล้ว ไม่ได้ขยาย tool เองเพราะขอบเขต conformance/
ถูกจำกัดโดย ADR-0011

2. invariant 5 ข้อของ field นี้ JSON Schema บังคับให้ไม่ได้ (ใบที่อ้างต้องมีจริง · tenant เดียวกัน
· subject เดียวกัน · ห้ามชี้ตัวเอง · ห้ามเป็นวง) — เขียนกำกับไว้ในตัว field ให้ผู้ผลิตบังคับเอง
· ฝั่ง devfactory-core ทางเดิน default ทำครบทั้ง 5 โดยธรรมชาติ แต่ถ้า caller ส่ง citation
เข้ามาเองยังไม่มีใครตรวจ — เขาลง remaining: ไว้แล้ว

ขอบคุณครับ 🙏