Handoff — P3D Pack 1 Phase 4 DRAFT v5 No-Hardcode — Opus Resume

Date: 2026-05-11 Author: GPT-5.5 Thinking / Incomex Hội đồng AI Receiver: New Opus session Workstream: P3D_INFORMATION_UNIT_TEXT_AS_CODE Current task: Patch Phase 4 implementation DRAFT v4 → DRAFT v5 Status: NO AGENT DISPATCH. NO SEED. NO MIGRATION.

0. One-line summary

We are blocked at P3D Pack 1 Phase 4 because implementation prompt drafts keep leaking hardcode / unsafe execution assumptions. The next Opus session must patch the Phase 4 vocab-prep prompt to DRAFT v5 with single-session executable gates and strict no-hardcode discipline.

1. Where we are in the roadmap

Original roadmap items:

Recover/write P3D spec — DONE.
Completed-state matrix — DONE.
Reconcile TAC logical units with native IU — IN PROGRESS.
Canonical IU contract — IN PROGRESS.

We are inside Pack 1 / Phase 4 of items 3–4.

Important detour already completed:

KB/vector/search reliability hardening — DONE/PASS, production acceptable.

Current Pack 1 phases:

Phase 1 inventory/design — DONE.
Phase 2 DDL extend IU schema — DONE/PASS.
Phase 3 hash/planner/birth alignment investigation — DONE/BLOCKED accepted.
Phase 4 governed migration readiness + no-hardcode — IN PROGRESS.

No TAC→IU migration has happened yet.

2. Critical philosophy — must be treated as law in this task

If not certainly right, it is wrong.

Not hardcoded does not mean “wrapped in a temp table”; it means every value is derived from a declared authoritative source at execution time, and the prompt states why that source is authoritative.

This is not decorative wording. GPT has rejected several drafts because they still contained hardcode in disguised form.

Forbidden patterns:

fixed seed lists copied from report/design/memory;
fixed row counts such as “14 rows”, “2 rows”, “17 types”, etc. used as logic;
literal target collection rows when registry/contract should derive them;
fuzzy species matching for production seed;
broad rollback by description prefix;
temp tables created in one psql session then used in another;
STOP gates written as prose instead of executable checks;
“agent adapts schema” where exact schema compatibility should be gated.

Allowed patterns:

live discovery query → compute delta → seed only delta → exact inserted-key capture → verify → commit;
every value has an authoritative source stated in the prompt;
counts are snapshots only;
read-only candidate reports for uncertain domains such as species mapping.

3. Most recent decision

DRAFT v4 was rejected. Do not run it.

Review path:

knowledge/dev/laws/dieu44-trien-khai/reviews/gpt-review-p3d-pack1-phase4-implementation-draft-v4-not-approved-2026-05-11.md

Directive path:

knowledge/dev/laws/dieu44-trien-khai/directives/gpt-directive-opus-p3d-pack1-phase4-draft-v5-single-session-no-hardcode-2026-05-11.md

Verdict:

phase4_draft_v4=REJECTED_FOR_DISPATCH
phase4_draft_v5_patch_allowed=true
agent_dispatch_allowed=false
seed_execution_allowed=false
species_mapping_executable=false
migration_allowed=false

4. Why DRAFT v4 was rejected

DRAFT v4 had real improvements, but still failed production certainty.

4.1 Temp table session bug

DRAFT v4 creates temp tables in one psql invocation:

_delta_section_type
_delta_pub_type
_delta_unit_kind

Then later tries to use those temp tables in another psql invocation.

Postgres temp tables are session-scoped, so they will not exist in the second session.

This is the main execution blocker.

4.2 STOP gates were prose, not executable

Example from v4:

STOP if no unique constraint/index on key

But the prompt only printed constraints; it did not compute a boolean and fail automatically.

Production gate must be executable SQL/bash failure, not a reminder.

4.3 Source table gate only printed rows

The prompt printed table names but did not verify all required objects exist.

4.4 Schema adaptation was too vague

The prompt said the agent should adapt INSERT columns to match schema. This is unsafe.

For v5, require exact compatible schema:

dot_config(key, value, description, updated_at)

If schema differs, STOP/BLOCKED.

4.5 Rollback safety still weak

Better model: run gates, delta, insert, verification in one transaction. If verification fails, rollback before commit. If commit succeeds, report exact inserted keys and run marker.

5. Current target prompt to patch

Patch this file in-place to DRAFT v5:

knowledge/dev/laws/dieu44-trien-khai/prompts/p3d-pack1-phase4-governance-vocab-species-prep-implementation-prompt-DRAFT.md

Create this report:

knowledge/dev/laws/dieu44-trien-khai/reports/p3d-pack1-phase4-implementation-draft-v5-patch-report.md

Do not create a new parallel prompt path unless absolutely necessary. We want one canonical DRAFT prompt path.

6. Required DRAFT v5 scope

Keep scope narrow.

6.1 Executable candidate

Only vocab prep may be an executable candidate.

This includes future seeding of:

missing vocab.section_type.* values derived from live tac_logical_unit.section_type;
missing vocab.publication_type.* values derived from live tac_publication.publication_type;
contract-required vocab.unit_kind.law_unit, where source is Pack 1 EVOLVE contract, not TAC-discovered data.

6.2 Read-only candidate only

Species mapping must remain SELECT/read-only candidate generation only.

No species_collection_map insert in DRAFT v5.

No hardcoded target collection rows.

No hardcoded composition level.

No fuzzy ILIKE '%law%' in executable logic. Fuzzy matching may appear only as candidate reporting and labelled candidate_not_approved.

6.3 Document-only

Hash provenance remains document-only:

unit_version.content_profile.source_hashes.tac_v1

No backfill. No migration.

7. Required DRAFT v5 execution model

DRAFT v5 must use one SQL session/transaction for the executable vocab section.

Recommended structure:

"${PSQL_BASE[@]}" -v run_marker="$RUN_MARKER" <<'SQL'
BEGIN;
SET LOCAL lock_timeout = '5s';
SET LOCAL statement_timeout = '60s';

-- executable gates: raise exception if not safe
-- create temp delta tables in THIS SAME session
-- dry-run preview SELECTs
-- INSERT ... RETURNING key into temp inserted table
-- verify inserted rows
-- verify fn_iu_create_plan law_unit no longer unresolved_vocab
-- COMMIT only after verification
COMMIT;
SQL

If a gate fails, RAISE EXCEPTION and transaction rolls back.

No separate psql sessions may depend on temp tables from prior sessions.

8. Required executable gates in DRAFT v5

DRAFT v5 must include executable gates, not prose-only checks.

Minimum gates:

G1 — exact compatible `dot_config` schema

Require all columns exist:

key
value
description
updated_at

STOP if any is missing.

G2 — unique or primary key support on `dot_config.key`

STOP if no unique index/constraint supports ON CONFLICT (key).

G3 — required source tables exist

Required tables:

dot_config
tac_logical_unit
tac_publication

If the prompt uses tac_section_type_vocab or tac_publication_type_vocab, gate them too. But do not require vocab tables if the actual delta only uses live used values from TAC rows.

G4 — source columns exist

Require:

tac_logical_unit.section_type
tac_publication.publication_type

G5 — no existing conflicting `dot_config` values

If a key already exists with a value that conflicts with the proposed value, STOP.

If a key exists with the same value, it is not a delta and should not be inserted.

G6 — run marker is available

The SQL must receive :'run_marker' correctly via -v run_marker="$RUN_MARKER".

G7 — post-insert planner verification

Before COMMIT, verify:

fn_iu_create_plan(p_unit_kind := 'law_unit', ...) does not return unresolved_vocab

Do not call fn_iu_create.

9. Required no-hardcode value sources

DRAFT v5 must explicitly state authoritative source for each category.

section_type

Authoritative source:

live public.tac_logical_unit.section_type values that are actually used

Reason:

This is production TAC data to be reconciled into IU; used values must be accepted before migration.

publication_type

Authoritative source:

live public.tac_publication.publication_type values that are actually used

Reason:

Publication type values needed for compatibility/render metadata must match live TAC publications.

law_unit

Authoritative source:

Pack 1 EVOLVE contract requiring TAC law units to become native IU law units

Reason:

TAC source rows do not carry unit_kind; unit_kind is a migration contract requirement, not a discovered TAC column.

It is acceptable for the DRAFT prompt to contain the literal law_unit only if it is clearly marked as contract-required and not a hardcoded snapshot value.

10. Required insert/rollback model

Inside the single transaction:

Compute deltas.
Preview deltas.
Insert from deltas only.
Capture inserted keys:

CREATE TEMP TABLE _inserted_keys(key text primary key);

WITH ins AS (
  INSERT INTO public.dot_config (...)
  SELECT ... FROM _delta...
  ON CONFLICT (key) DO NOTHING
  RETURNING key
)
INSERT INTO _inserted_keys SELECT key FROM ins;

Verify inserted keys.
Verify planner.
COMMIT.

Rollback before commit is automatic on exception.

After commit, if manual rollback is needed, it must delete only exact keys listed in report for that run, not pattern/prefix matching.

Do not use:

DELETE FROM dot_config WHERE description LIKE 'Seeded from ...%'

Do not use broad:

DELETE FROM dot_config WHERE description = run_marker

as the only rollback strategy unless the exact key list is also captured and reported. Prefer exact keys.

11. Required species section in v5

Species section must be read-only only.

It may report candidates such as:

current entity_species rows;
current species_collection_map rows;
collections with missing species_code;
candidate law species if query finds it.

But it must say:

species_mapping_executable=false
species_mapping_requires_separate_GPT_User_approved_prompt=true

No species INSERT.

No target collection insert rows.

No subordinate literal.

12. Required report content from Opus patch

Patch report must include:

phase4_draft_v5_status=PATCHED
vocab_executable_candidate=true
species_mapping_executable=false
hash_provenance_document_only=true
single_session_transaction=true
executable_stop_gates=true
temp_table_cross_session_bug_fixed=true
no_hardcoded_seed_list=true
psql_run_marker_fixed=true
requires_GPT_User_review_before_dispatch=true

Also list top 7 fixes from v4.

13. What Opus must return in chat

Return only:

DRAFT v5 prompt path.
Patch report path.
Top 7 fixes from v4.
Which parts are executable candidate vs read-only candidate vs document-only.
Confirm GPT/User review required before dispatch.

14. Do not do these things

Do not run agent.
Do not seed.
Do not migrate.
Do not ask User to run v5 until GPT reviews it.
Do not split into many micro-prompts.
Do not re-open Phase 3 unless a real blocker appears.

15. Most important paths

DRAFT v4 current prompt:

knowledge/dev/laws/dieu44-trien-khai/prompts/p3d-pack1-phase4-governance-vocab-species-prep-implementation-prompt-DRAFT.md

DRAFT v4 rejection review:

knowledge/dev/laws/dieu44-trien-khai/reviews/gpt-review-p3d-pack1-phase4-implementation-draft-v4-not-approved-2026-05-11.md

DRAFT v5 directive:

knowledge/dev/laws/dieu44-trien-khai/directives/gpt-directive-opus-p3d-pack1-phase4-draft-v5-single-session-no-hardcode-2026-05-11.md

Patch report target:

knowledge/dev/laws/dieu44-trien-khai/reports/p3d-pack1-phase4-implementation-draft-v5-patch-report.md

16. Suggested first message to Opus new session

Paste this to Opus:

Bạn đang tiếp tục P3D Pack 1 Phase 4. Hãy đọc handoff sau trước rồi làm đúng nhiệm vụ, không chạy agent, không seed, không migration:

knowledge/dev/laws/dieu44-trien-khai/handoffs/handoff-p3d-pack1-phase4-draft-v5-no-hardcode-opus-resume-2026-05-11.md

Nhiệm vụ duy nhất: patch Phase 4 implementation DRAFT v4 thành DRAFT v5 theo directive:

knowledge/dev/laws/dieu44-trien-khai/directives/gpt-directive-opus-p3d-pack1-phase4-draft-v5-single-session-no-hardcode-2026-05-11.md

Target prompt:
knowledge/dev/laws/dieu44-trien-khai/prompts/p3d-pack1-phase4-governance-vocab-species-prep-implementation-prompt-DRAFT.md

Patch report:
knowledge/dev/laws/dieu44-trien-khai/reports/p3d-pack1-phase4-implementation-draft-v5-patch-report.md

Yêu cầu bắt buộc:
- If not certainly right, it is wrong.
- Vocab prep only can be executable candidate.
- Species mapping read-only candidate only.
- Hash provenance document-only.
- One SQL session/transaction for gates → delta → dry-run → insert → verify → commit.
- STOP gates executable, not prose.
- No hardcoded seed list.
- No temp table across psql sessions.
- No seed/migration/agent dispatch.

Sau khi patch, chỉ trả về: prompt path, report path, top 7 fixes, scope executable/read-only/document-only, và xác nhận cần GPT/User review trước dispatch.

17. Final state

phase4_draft_v4=REJECTED_FOR_DISPATCH
phase4_draft_v5_patch_allowed=true
agent_dispatch_allowed=false
seed_execution_allowed=false
species_mapping_executable=false
migration_allowed=false
next_action=OPUS_PATCH_DRAFT_V5_SINGLE_SESSION_EXECUTABLE_GATES_NO_HARDCODE

Handoff — P3D Pack 1 Phase 4 DRAFT v5 No-Hardcode — Opus Resume

0. One-line summary

1. Where we are in the roadmap

2. Critical philosophy — must be treated as law in this task

3. Most recent decision

4. Why DRAFT v4 was rejected

4.1 Temp table session bug

4.2 STOP gates were prose, not executable

4.3 Source table gate only printed rows

4.4 Schema adaptation was too vague

4.5 Rollback safety still weak

5. Current target prompt to patch

6. Required DRAFT v5 scope

6.1 Executable candidate

6.2 Read-only candidate only

6.3 Document-only

7. Required DRAFT v5 execution model

8. Required executable gates in DRAFT v5

G1 — exact compatible dot_config schema

G2 — unique or primary key support on dot_config.key

G3 — required source tables exist

G4 — source columns exist

G5 — no existing conflicting dot_config values

G6 — run marker is available

G7 — post-insert planner verification

9. Required no-hardcode value sources

section_type

publication_type

law_unit

10. Required insert/rollback model

11. Required species section in v5

12. Required report content from Opus patch

13. What Opus must return in chat

14. Do not do these things

15. Most important paths

16. Suggested first message to Opus new session

17. Final state

G1 — exact compatible `dot_config` schema

G2 — unique or primary key support on `dot_config.key`

G5 — no existing conflicting `dot_config` values