GPT Review — 23-P3B Execution Result and P3C Directive

Date: 2026-05-07
Reviewer: GPT-5.5 Thinking / Incomex Hội đồng AI
Reviewed: knowledge/dev/laws/dieu44-trien-khai/reports/23-p3b-iu-edit-draft-schema-report.md rev1
Related: knowledge/dev/laws/dieu44-trien-khai/reviews/opus-review-23-p3b-execution-result-2026-05-07.md

Verdict

23-P3B PASS. No supplemental Agent action needed.

Agent executed correctly. Opus review is accurate.

P3B is closed. Proceed to P3C function prompt design, not immediate execution.

Evidence accepted

• phase_status=PASS
• p3c_readiness=READY
• V1–V14 all PASS
• unit_edit_draft created: 18 columns, 8 CHECK constraints, 3 FKs, 4 custom indexes
• unit_edit_comment created: 13 columns, 5 CHECK constraints, 3 FKs, 2 custom indexes
• information_unit.sort_order added as nullable integer
• idx_iu_parent_sort created as partial index
• iu_edit.policy.default_mode=auto_apply
• iu_edit.schema.version=p3b-v1
• IU/UV row counts unchanged: 6 → 6 / 6 → 6
• no new functions created
• P3A gateway allow-list intact
• owner = directus
• PUBLIC INSERT/UPDATE/DELETE absent
• hard boundaries honored

Runtime state after P3B

• Gateway is ready for fn_iu_apply_edit_draft marker.
• Draft/comment schema exists.
• No edit/comment/apply functions exist yet.
• fn_iu_apply_edit_draft does not exist yet.
• sort_order exists for structural parent/child ordering.

Important P3C caution

P3B report notes:

UV lifecycle convention grep returned empty.

Do not infer lifecycle behavior from grep. P3C preflight must inspect the full fn_iu_create source and/or existing UV rows to determine how unit_version.lifecycle_status is set. If convention cannot be determined confidently, default to matching the observed current UV row convention or block for GPT/User decision.

New User requirement to carry into P3C

The User clarified:

A good design is one where nobody has to remember the process.
For comments, AI/Agents should be able to “come in and give an opinion” naturally. The system should attach author/time/status/defaults automatically. Only the main reviewer/Opus/User needs to understand approval/apply flow.

This requirement is recorded at:

knowledge/dev/laws/dieu44-trien-khai/reviews/gpt-note-pack23-natural-comment-ux-requirement-2026-05-07.md

P3C must include a natural comment interface, not only a low-level draft_id function.

Directive to Opus — P3C function prompt design

Create prompt, do not dispatch:

knowledge/dev/laws/dieu44-trien-khai/prompts/23-p3c-iu-edit-draft-functions-prompt.md

Report path:

knowledge/dev/laws/dieu44-trien-khai/reports/23-p3c-iu-edit-draft-functions-report.md

P3C objective

Create canonical PG functions for the editorial edit workflow:

1. fn_iu_edit_plan(...) — dry-run/read-only plan
2. fn_iu_create_edit_draft(...) — create draft from current IU
3. fn_iu_comment_edit_draft(...) — low-level comment by draft_id
4. fn_iu_comment_current_draft(...) or equivalent — natural comment helper by canonical_address/context
5. fn_iu_apply_edit_draft(...) — apply draft to official version
6. fn_iu_edit(...) — convenience wrapper: create draft + auto-apply when policy permits

GPT originally expected 5 functions, but the User’s natural-comment requirement adds one helper. Opus may propose merging low-level/natural comment into one overloaded function only if it keeps Agent UX simple and unambiguous.

Hard boundaries

• No table DDL.
• No schema changes.
• No trigger changes.
• No gateway changes.
• No vector mutation.
• No cleanup.
• No direct IU/UV writes outside canonical apply function.
• No Pack 2C.

Required preflight gates

P3C prompt must inspect and STOP if:

• any target function already exists, unless prompt explicitly supports idempotent already-created state;
• P3B tables/column missing or wrong shape;
• P3A gateway allow-list missing fn_iu_apply_edit_draft;
• unit_edit_draft/unit_edit_comment owner/grants unexpected;
• fn_content_hash missing;
• fn_iu_verify_invariants missing;
• fn_iu_create missing or its lifecycle convention cannot be determined;
• unit_version contract changed unexpectedly;
• current role/owner pattern cannot be determined.

Preflight must capture:

• current IU/UV counts;
• draft/comment counts;
• source/metadata of existing Pack 22 functions;
• current UV lifecycle values from real rows;
• full fn_iu_create source excerpt or full source path in report.

Function design requirements

1. fn_iu_edit_plan(...)

Purpose: read-only dry-run.

Inputs should be address-first, e.g.:

• p_canonical_address text
• p_draft_body text
• p_actor text
• optional p_draft_title text
• optional p_reason text

Return JSONB with statuses such as:

• plan_ok
• not_found
• invalid_input
• no_change
• existing_open_drafts
• policy_auto_apply
• policy_require_review

No body leak beyond short preview/hash unless explicitly safe.

2. fn_iu_create_edit_draft(...)

Creates a draft row only. Does not touch IU/UV.

Must:

• resolve current IU by canonical_address;
• lock or safely read current IU/version anchor;
• read base version id/seq/hash/body;
• validate actor/body/title;
• compute draft hash using fn_content_hash;
• detect no-change and return no_change unless creating draft anyway is explicitly justified;
• insert unit_edit_draft;
• return draft id, status draft_created, base info, hash preview.

It must populate canonical_address from IU, not trust caller text beyond lookup.

3. fn_iu_comment_edit_draft(...)

Low-level append-only comment by draft id.

Must:

• validate draft exists;
• validate author/comment body/comment_kind;
• default author_type='agent' and comment_kind='general' where appropriate;
• insert into unit_edit_comment;
• allow comments on open/stale/applied/withdrawn drafts for audit;
• return status comment_added.

4. Natural comment helper

Add one helper, e.g.:

fn_iu_comment_current_draft(p_canonical_address text, p_author text, p_comment_body text, p_comment_kind text DEFAULT 'general', p_context jsonb DEFAULT '{}'::jsonb)

Resolution policy:

• if exactly one open draft for address → attach automatically;
• if multiple open drafts → return ambiguous_draft with candidate IDs/summaries;
• if no open draft → return no_open_draft;
• never silently attach to the wrong draft.

This is required by User’s “AI cứ vào comment tự nhiên” principle.

5. fn_iu_apply_edit_draft(...)

Applies one draft to official version.

Must:

• SECURITY DEFINER;
• set app.canonical_writer='fn_iu_apply_edit_draft' transaction-local before IU/UV writes;
• lock target IU row FOR UPDATE;
• verify draft exists and status=open;
• verify base version is still current, else mark/return stale_base according to policy;
• compute/verify draft hash;
• determine next version_seq=max(version_seq)+1 under lock;
• determine unit_version.lifecycle_status convention safely;
• insert new unit_version official row;
• update IU anchors/content/profile/title if applicable;
• mark applied draft as applied with applied_by, applied_at, applied_version_ref;
• mark other open drafts for same IU/base as stale_base with stale_at;
• insert apply review/system comment using p_review_note or default message;
• call fn_iu_verify_invariants and require all_pass;
• rollback on fail via exception;
• return JSONB status applied with new version info.

6. fn_iu_edit(...) wrapper

For Agent/User convenience.

• Reads iu_edit.policy.default_mode.
• If auto_apply, create draft then apply in same caller transaction.
• If require_review, create draft and return draft_created_review_required.
• Should not write IU/UV directly; it should delegate to fn_iu_apply_edit_draft so gateway marker list remains 2 values.

Security requirements

• All write functions should be SECURITY DEFINER with SET search_path=pg_catalog,public.
• REVOKE PUBLIC on all new functions.
• GRANT only intended role(s), following Pack 22 pattern.
• Direct table writes remain discouraged; functions are canonical path.

Testing requirements

P3C prompt should include tests for:

• plan no-write;
• draft create from a pilot/current IU;
• low-level comment add;
• natural comment helper attaches when exactly one open draft;
• natural comment helper returns ambiguous_draft when multiple open drafts exist;
• apply draft creates exactly one new UV and updates IU anchors;
• apply inserts system/review comment;
• stale_base behavior when base changed;
• wrapper fn_iu_edit auto-applies under default policy;
• direct IU/UV wrong-door still blocked;
• PUBLIC EXECUTE absent and intended grants present;
• IU/UV counts change only in expected tests;
• no vector mutation.

Use dynamic pilot addresses/drafts. Retain pilots; no cleanup.

Report requirements

Report must include:

• phase_status PASS/FAIL/CRITICAL;
• p3d_readiness READY/BLOCKED;
• functions created list;
• privileges/grants;
• test matrix;
• created pilot addresses/draft IDs;
• IU/UV/draft/comment counts before/after;
• lifecycle convention decision;
• gateway marker verification;
• boundaries honored.

Design note for Opus

P3C is more complex than P3B. Opus should first create a prompt draft and stop for GPT/User review. It should not attempt to dispatch.

Keep it practical: do not implement diff/patch, three-way merge, line comments, semantic lint, vector outbox, or role separation in P3C.

Summary

P3B completed the schema layer. P3C should create the canonical functions that make the workflow natural: Agents draft and comment without knowing internals; reviewer/apply function safely turns a draft into an official version through the existing gateway and invariants.