GPT Review — Pack 22 dot-iu-create Wrapper Design

Date: 2026-05-05 Reviewer: GPT-5.5 Thinking / Incomex Hội đồng AI Reviewed: knowledge/dev/laws/dieu44-trien-khai/design/22-dot-iu-create-wrapper-design.md rev1

Verdict

Direction PASS, but rev2 required before execution design.

Pack 22 correctly frames dot-iu-create as a wrapper over existing IU/UV + gates + birth trigger. It does not invent a new birth lifecycle. However, the current design still has several hardcode/implementation risks that should be fixed before writing an execution prompt.

What is correct

• dot-iu-create is a wrapper, not a new birth process.
• No raw insert into birth_registry.
• Existing trigger should create the birth row.
• Default dry-run is correct.
• Idempotency on canonical_address is correct.
• Vocab validation from dot_config is correct in principle.
• The IU+UV transaction follows the P2B-P1 proven path.

Required rev2 patches

P1 — Replace CLI-required vocab values with auto-discovery/default policy

Current CLI requires:

• --unit-kind
• --section-type

This still makes Agent/user remember vocab values. Better wrapper behavior:

• allow explicit --unit-kind / --section-type;
• if absent, discover defaults from dot_config or a wrapper config key;
• if no default exists and multiple choices exist, stop with available values.

Proposed hierarchy:

1. CLI arg if provided.
2. dot_config key such as:
   • dot_iu_create.default_unit_kind
   • dot_iu_create.default_section_type
3. If absent, query available vocab.unit_kind.% / vocab.section_type.% and STOP with choices.

This avoids replacing CTE ritual with “remember magic vocab tokens.”

P2 — Do not hardcode PG connection details

Current design says:

docker exec -i postgres psql -U directus -d directus

Make it configuration-driven:

• source DOT environment if available;
• support env vars:
  • PG_CONTAINER
  • PGUSER
  • PGDATABASE
• default only as fallback documented snapshot, not timeless truth.

The wrapper should print connection target in dry-run/report.

P3 — Avoid unsafe SQL interpolation / escaping by hand

The design currently says escape body via sed "s/'/''/g". This is fragile for multiline content, backslashes, JSON, and shell quoting.

Rev2 should require psql variables or a temp SQL file with safe variable binding.

Preferred pattern:

• write body to a temp file;
• pass values with psql -v canonical_address=... -v body_file=... where feasible;
• use pg_read_file only if safe and accessible, or COPY/temp table pattern;
• at minimum, use PostgreSQL dollar-quoting with generated unique tag and collision check.

Execution pack should not rely on naive sed escaping.

P4 — Verify required functions/extensions dynamically

Before execute/dry-run, wrapper should verify:

• gen_random_uuid() available;
• digest(text,text) or equivalent hash function available;
• trg_birth_information_unit exists/enabled;
• fn_birth_registry_auto exists;
• IU/UV required columns exist.

Do not assume pgcrypto or function availability.

P5 — Do not hardcode “UV birth = 0” as permanent semantics without metadata check

Current design says UV birth expected 0 because subordinate. That is correct as current design, but should be verified from metadata:

SELECT birth_code_strategy
FROM collection_registry
WHERE collection_name='unit_version';

If unit_version strategy changes later, wrapper verification should adapt or warn based on metadata.

P6 — Clarify idempotency behavior for existing rows

If canonical address exists:

• verify whether IU has at least one UV;
• verify whether birth row exists;
• return status:
  • exists_complete
  • exists_missing_birth
  • exists_missing_version
• do not silently report success if existing IU is incomplete.

This aligns with main + safety-belt philosophy.

P7 — Explicitly separate dry-run SQL from executable SQL

Dry-run may print sanitized SQL/plan, but should not print full body if body may contain large or sensitive content. It can print:

• canonical_address;
• body length;
• hash preview;
• planned INSERT tables;
• vocab selected.

Avoid dumping full body into logs by default.

P8 — Tool registration must be separate gate

§10 says E4 register in dot_tools via PG INSERT. This should not be embedded as assumed raw insert.

Rev2 should say:

• DOT registration path must be inspected/approved separately;
• use existing DOT registry path if available;
• no raw dot_tools insert unless a later execution pack authorizes it.

P9 — Add “no cleanup pilot row” default

§10 includes E5 cleanup pilot IU if needed. For this wrapper, cleanup should not be part of initial implementation by default.

If a test row is created, keep it unless GPT/User approves cleanup. Deleting IU/UV may interact with birth traces and ghost/orphan detectors.

P10 — Add health-signal requirement for fallback/backfill

If wrapper detects existing IU without birth and invokes or recommends backfill, this must be emitted as health warning, not hidden as success.

For design:

• wrapper should not run backfill automatically in v1;
• it should report exists_missing_birth and point to backfill/remediation.

Immediate directive to Opus

Patch Pack 22 to rev2 with P1–P10. Do not create an execution prompt yet.

After rev2, return for GPT/User review.

Hard boundaries

• no runtime mutation;
• no DOT script patch;
• no raw birth_registry insert;
• no raw dot_tools insert;
• no Pack 2C dispatch;
• no hardcoded vocab, connection details, counts, or schema assumptions.

Summary

The wrapper concept is approved. The implementation design needs to become configuration/query-driven before it can safely become a DOT tool.