GPT Review — 23-P3 Proposal/Merge Design + Comments Directive

Date: 2026-05-06
Reviewer: GPT-5.5 Thinking / Incomex Hội đồng AI
Reviewed: knowledge/dev/laws/dieu44-trien-khai/design/23-p3-iu-proposal-merge-implementation-design.md rev1

Verdict

Direction accepted, but rev2 required before execution planning.

Opus successfully recreated the missing 23-P3 design pack and aligned with Model D hybrid. The design is strong and correctly keeps unit_version as merged history while introducing unit_proposal as the Git-like PR/change-request layer.

However, the User clarified an important requirement:

Agents/AI must be able to comment naturally, with author identity and timestamp.

This must be part of the design now, before implementation, because review/commenting is core to text-as-code and multi-agent collaboration.

Accepted decisions

1. Model D hybrid is accepted.
2. unit_proposal as PR/change-request object is accepted.
3. unit_version remains merged-truth-only.
4. fn_iu_propose_edit does not need gateway allow-list if it writes only unit_proposal.
5. Gateway allow-list should include only canonical writers that write IU/UV:
   • fn_iu_create
   • fn_iu_merge_edit
   • fn_iu_edit
6. sort_order as a core column is accepted conceptually, because the system is greenfield and ordering is likely a hot render path.
7. Parent/child remains structural containment, while domain/professional composition uses universal_edges.

Required correction: comment/review discussion layer

Do not overload unit_proposal.review_note for natural multi-agent comments.

A single review_note field is insufficient because:

• multiple Agents may comment many times;
• comments need author identity;
• comments need timestamp;
• comments may refer to proposal as a whole or to a specific slice/line/range later;
• reviewer may need threaded discussion or at least ordered discussion history;
• audit requires immutable comment history.

Decision

Add a separate comment/discussion primitive in the design.

Recommended table name:

unit_proposal_comment

This is standard PR-review modeling: proposal object + comments/discussion object.

Required 23-P3 rev2 patches

P1 — Add unit_proposal_comment schema design

Add to §3 or a new §3B.

Concept fields:

Column	Type	Purpose
id	uuid	PK
proposal_id	uuid	FK → unit_proposal(id)
unit_id	uuid	Denormalized FK → IU for query/index speed
author_ref	text	Agent/User who commented
author_type	text	user / agent / system
comment_body	text	Natural-language comment
comment_kind	text	general / review / change_request / approval / system
created_at	timestamptz	timestamp
resolved_at	timestamptz nullable	for review comments / change requests
resolved_by	text nullable	who resolved
parent_comment_id	uuid nullable	optional threading
target_path	text nullable	future: JSON path / section path / line range
metadata	jsonb	future extension

Constraints/design:

• FK proposal_id → unit_proposal(id)
• optional FK parent_comment_id → unit_proposal_comment(id)
• CHECK comment_kind in allowed values
• suggested index (proposal_id, created_at)
• suggested index (unit_id, created_at)

P2 — Add comment functions

Add to §4 function set:

• fn_iu_comment_proposal(p_proposal_id, p_author, p_comment_body, p_comment_kind DEFAULT 'general', p_parent_comment_id DEFAULT NULL, p_target_path DEFAULT NULL)
• fn_iu_resolve_comment(p_comment_id, p_resolver, p_note DEFAULT NULL)

Phase 1 minimum:

• fn_iu_comment_proposal is enough.
• fn_iu_resolve_comment can be Phase 2 if needed.

Return statuses:

• comment_added
• proposal_not_found
• invalid_status if proposal is closed and policy disallows comments
• invalid_input

P3 — Add review/merge policy with comments

Update merge algorithm:

• For Phase 1 auto-merge: comments optional.
• For require_review policy: merge should require either:
  • explicit reviewer actor, or
  • at least one approval comment of kind approval, depending on policy.

Do not enforce strict approval in Phase 1 unless policy says so. But design hook must exist.

P4 — Add comment workflow example

Add scenario:

1. Agent A proposes edit.
2. Agent B comments: “logic ok, missing edge reference.”
3. Agent C comments or proposes alternative.
4. Reviewer adds approval/change request.
5. Merge uses proposal + comment history as review evidence.

P5 — Update phase plan

P3B should include unit_proposal_comment schema and fn_iu_comment_proposal if we want comments available from day one.

Suggested revised split:

• P3A: gateway allow-list patch.
• P3B: unit_proposal + unit_proposal_comment schema + propose/comment functions.
• P3C: merge function + wrapper + tests.
• P3D: first real IU parent/child pilot.

P6 — Update risks/open decisions

Add risks:

• comment retention / editability: comments should be append-only in Phase 1; no edit/delete.
• spam/noise by Agents: later need comment_kind and maybe summary/resolve.
• line/range comments: defer target_path semantics until render/diff layer exists.
• author identity must be explicit and non-empty.

Additional GPT concerns on rev1

C1 — proposed_title vs title storage must be handled carefully

Current title appears in identity_profile->>'title', not in UV. If merge updates title, it must update IU identity_profile, which is a direct IU update and requires gateway marker.

Design should explicitly state:

• Phase 1 may support body-only edit first; or
• if title edit is included, merge updates identity_profile.title in the same transaction.

Do not leave title behavior ambiguous.

C2 — fn_iu_edit marker may not need separate allow-list value

If fn_iu_edit only calls fn_iu_merge_edit, and fn_iu_merge_edit sets the marker immediately before IU/UV writes, then fn_iu_edit itself may not need to be in the allow-list.

Rev2 should clarify one of two choices:

• allow-list only fn_iu_create,fn_iu_merge_edit; or
• include fn_iu_edit because wrapper performs IU/UV writes directly.

Prefer the first if wrapper delegates writes to merge function.

C3 — fn_iu_reject_edit should not be required in Phase 1 unless comment/review needs it

Reject is useful, but if we are trying to keep Phase 1 compact, proposal + comment + merge may be enough. Reject can be Phase 1.5 unless it is needed for cleanup.

Opus may keep it in Phase 1, but justify.

Directive to Opus

Patch design pack to rev2:

knowledge/dev/laws/dieu44-trien-khai/design/23-p3-iu-proposal-merge-implementation-design.md

Apply P1–P6 and address C1–C3.

Do not create an execution prompt yet.

Expected Opus response

Opus should upload rev2 and summarize:

• comment model added;
• comment functions added;
• phase plan updated;
• title edit clarified;
• allow-list marker clarified;
• reject phase decision clarified.

Hard boundaries

• No DDL/DML.
• No runtime mutation.
• No function/trigger changes.
• No vector mutation.
• No cleanup.
• No Pack 2C.

Summary

The proposal/merge architecture is accepted, but review comments are not optional. Multi-agent text-as-code needs a place for natural comments with author and timestamp. Add unit_proposal_comment now so Agents can collaborate like a PR review, while keeping implementation phased.