KB-3726

GPT Review — README Decision for 22-P3-P2 rev7

5 min read Revision 1

gpt-reviewpack-22p3p2readmetrigger-guardrev7

GPT Review — README Decision for 22-P3-P2 rev7

Date: 2026-05-06
Reviewer: GPT-5.5 Thinking / Incomex Hội đồng AI
Subject: Should README be written in the same Agent run as P3-P2 rev7?

Verdict

Do not make the P3-P2 runtime Agent write the README.

But do not wait until after enforcement either. Create a minimal standing README before dispatching rev7.

Reason: P3-P2 trigger guard error will point callers to iu_create.gateway.readme_path. If that path does not exist, the guard blocks correctly but the guidance is incomplete. The README does not require runtime evidence from the rev7 run; the minimum correct guidance is already known.

Rationale

Why not inside the same Agent run?

P3-P2 rev7 is a runtime enforcement pack. It should stay focused:

deploy guard function/triggers;
test canonical create;
test direct writes are blocked;
enforce mode only if all tests pass;
cleanup if fail.

Adding README creation to the same run creates unnecessary coupling between KB/doc mutation and runtime enforcement. If doc upload fails, runtime result becomes ambiguous. If runtime fails, README may still be valid. They should not share a failure boundary.

Why not after the run?

Because the guard error message already returns the README path. If enforcement passes before the README exists, wrong-door callers receive a broken or empty instruction path.

Correct sequencing

Opus creates a minimal KB README now.
GPT/User approve quickly.
Dispatch P3-P2 rev7 runtime enforcement.
After PASS, optionally patch README with final deployed state/report link.

Required README path

knowledge/dev/laws/dieu44-trien-khai/readme/iu-create-gateway-readme.md

This path must match the existing dot_config key:

iu_create.gateway.readme_path

Minimal README content

Opus should create the README with this content, adjusting only formatting if needed:

# IU Creation Gateway README

> Status: Gateway prepared / enforcement pending P3-P2.  
> Canonical path: `public.fn_iu_create(...)`  
> Plan/dry-run path: `public.fn_iu_create_plan(...)`

## Rule

Do not create or modify IU objects by direct table writes.

Forbidden paths:

- `INSERT INTO public.information_unit ...`
- `UPDATE public.information_unit ...`
- `INSERT INTO public.unit_version ...`
- `UPDATE public.unit_version ...`
- Directus/API writes that map directly to those tables
- Agent/DOT scripts that rebuild the IU/UV insert flow manually

Use the canonical PG contract instead.

## Create a new IU

First dry-run:

```sql
SELECT public.fn_iu_create_plan(
  canonical_address := '<stable-address>',
  title             := '<title>',
  body              := '<body>',
  actor             := '<actor>'
);

Then create:

SELECT public.fn_iu_create(
  canonical_address := '<stable-address>',
  title             := '<title>',
  body              := '<body>',
  actor             := '<actor>'
);

The function creates IU + first UV + anchors. The existing PG birth triggers create the birth record automatically. The function verifies invariants before returning created.

If you see “IU Gateway blocked”

You attempted a direct IU/UV table write. Stop and call fn_iu_create_plan / fn_iu_create instead.

Do not manually set app.canonical_writer. That marker is internal to the canonical function and is not a user/API contract.

Existing or duplicate IU

If the address already exists, fn_iu_create returns an existing-state result such as exists_complete. Treat incomplete states as health/remediation cases, not successful creation.

Imports and migrations

Controlled imports/migrations are not normal creation paths. They require explicit exemption policy and audit. Do not assume direct insert is allowed.

Current limitations

The gateway marker is a wrong-door blocker, not a security boundary.
Future layers may add detector coverage and role separation.
Adapter/UI flows should be thin wrappers around fn_iu_create, not separate implementations.


## Directive to Opus

Create the README at the path above as a separate KB document. Do not modify runtime. Do not change P3-P2 rev7 except if the path in prompt/dot_config does not match the README path.

After README creation, return for GPT/User quick confirmation or dispatch rev7 if the user has already authorized.

## Rev7 status

P3-P2 rev7 trigger rename is accepted conceptually. The remaining prerequisite before dispatch is that the README path exists.