dot-iu-cutter v0.1 — P0-6 review_decision Migration Design

Date: 2026-05-15 Status: P0 MIGRATION DESIGN — Item 4 of 6 Scope: DESIGN ONLY. No DDL, no SQL, no CREATE/ALTER TABLE, no column DDL, no migration execution, no PG mutation. Master: migration-design/dot-iu-cutter-v0.1-p0-migration-design-master-2026-05-15.md

---

1. Purpose

P0-6 establishes the persistent PG SSOT for REVIEW stage outcomes — independent AI review or human review verdicts on a manifest. CUT (D1 §4.6) pre-condition is "manifest in PASS state" — and the PASS state IS materialized as a review_decision row. P0-6 also implements governance_event umbrella sub-kind (Đ44 Step 3) for review verdicts.

2. Source Design References

• D2 Manifest and Operator Contract — §4.6 (REVIEW contract checklist), §4.7 (independent review), §4.8 (risk gating triggers human review), §6 (schema gap item 3).
• D1 Operational Design — §4.5 (REVIEW stage), §4.6 (CUT preconditions), §4.14 (DOT-pair).
• D9 §4.10 governance role mapping (G-1 reviewer roles).
• Đ44 Step 3 outcome — governance_event umbrella accepts review_decision as P0 sub-kind.
• Đ24 Step 1 ratified (status, kind, risk_class enums).
• G-1 + G-3 closures — reviewer authority hierarchy.
• P0 Schema Planning §5.6 P0-6 detail.

3. Logical Object / Table Intent

Primary table: review_decision

Umbrella mapping (Đ44 Step 3):

• review_decision is a P0 sub-kind under the governance_event family umbrella.
• v0.1 design uses a dedicated table review_decision (clean per-sub-kind ergonomics).
• Future Đ44 may consolidate into a single governance_event table with event_kind discriminator — supported via §4.2 mapping field.

Target DB: directus. Target Schema: TAC schema (joint with manifest family) OR new governance schema — same decision as P0-2 §9 item 1. Target Layer: Não (analytical / state record per D5 storage pattern).

4. Proposed Fields at Conceptual Level

4.1 review_decision

Field name	Type-class	Nullable	Notes
review_decision_id	uuid OR bigserial	NO	primary identifier
governance_event_kind	enum-ref	NO	fixed value review_decision for this table; supports future umbrella consolidation
manifest_id	FK to manifest_envelope	NO	review target
manifest_version	text (semver)	NO	exact manifest version reviewed
review_scope	enum-ref	NO	values: envelope_level / unit_level / mixed
manifest_unit_block_composite_id	composite FK (manifest_id, unit_local_id)	YES	populated when review_scope='unit_level' or 'mixed'; null for envelope-only review
status	enum-ref	NO	values: pending / in_review / pass / fail / needs_human / escalated / superseded per D2 §4.6
verdict	enum-ref	NO	values: PASS / FAIL / NEEDS_HUMAN (D2 §4.6 returns one of these); terminal verdicts
findings	JSONB	NO	structured per D2 §4.6 checklist (10 items): no_loss, no_overlap, c1a_three_question_test, c1a_rule_citations_valid, vocabulary_dieu24_conformant, canonical_parent_unique, birth_gate_ready, length_within_policy, edge_readiness_present, body_source_policy_consistent; each carrying {result: bool, severity, note}
reviewer_class	enum-ref	NO	values: ai / human / council / dot_pair_verifier
reviewer_identity	JSONB	NO	structured envelope per §5 below — AI capability fingerprint OR human identifier (D8 §8 missing-instrumentation #8)
reviewer_independence_evidence	JSONB	YES	proof of separate execution context (per D2 §4.7) — captures process/context fingerprint
risk_class_assessment	enum-ref to Đ24/Đ32	NO	reviewer's risk classification (may differ from manifest's risk_class)
escalation_ref	FK to decision_backlog_entry (P0-5)	YES	FK to backlog entry routing this review for human/council attention
prior_review_decision_id	FK to review_decision	YES	for re-review chains
superseded_by_review_decision_id	FK to review_decision	YES	when a re-review supersedes this one
decision_at	timestamp UTC	NO	when verdict was rendered
decided_by	text actor	NO	actor identifier (overlaps with reviewer_identity for AI; named seat for human)
tool_revision	text	YES	cutter revision used in review
review_duration_ms	integer	YES	metric hook; populated when measurable
cross_signed_by_dot_verifier	boolean	NO	true if DOT-pair verifier co-signed this review verdict (cross-link with P0-3/P0-4)
version	text (semver)	NO	record version per Đ38

4.2 reviewer_identity JSONB envelope (§4.1 field structure)

reviewer_identity_envelope_shape:
  for_ai_reviewer:
    type: "ai"
    model: text (e.g. "claude-opus-4-7")
    model_revision: text
    execution_context_fingerprint: text/hash (separate execution context evidence)
    invocation_id: text/uuid
  for_human_reviewer:
    type: "human"
    seat_role: text (Đ37 role)
    seat_occupant_alias: text (NOT direct PII; pseudonymous identifier per G-5 audience scope)
    authorization_ref: text (reference to Đ37 SOP authorization record)
  for_council:
    type: "council"
    quorum_count: integer
    quorum_required: integer
    council_session_id: text
  for_dot_pair_verifier:
    type: "dot_pair_verifier"
    verifier_dot_id: text ("dot-iu-cutter-verify")
    verifier_tool_revision: text
    signature_payload_ref: text (cross-link with P0-3 signature record)

The envelope is JSONB to allow polymorphism; the type field discriminates.

5. Field Ownership / Vocabulary Dependency

Field	Vocabulary owner
governance_event_kind	Đ24 Step 1 P0 subset extension — review_decision is a controlled term
review_scope enum	cutter-local v0.1; Đ24 confirmation path
status enum	Đ24 Step 1 ratified envelope (reused)
verdict enum	cutter-local v0.1 (PASS/FAIL/NEEDS_HUMAN); Đ24 ratification recommended
reviewer_class enum	Đ24 Step 1 + Đ37 role mapping cross-law
findings JSONB structured per checklist	D2 §4.6 canonical checklist (10 items); structured schema in JSONB
risk_class_assessment	Đ24 Step 1 ratified

6. Lifecycle

[Review entry lifecycle]
pending  (created when MARK emits a manifest needing review)
   ↓
in_review (reviewer picks up; reviewer_identity populated)
   ↓
   ├─→ pass     (verdict=PASS; unlocks CUT)
   ├─→ fail     (verdict=FAIL; manifest rejected; CUT blocked)
   └─→ needs_human (verdict=NEEDS_HUMAN; escalation_ref populated → P0-5 backlog)
                ↓
            escalated  (status; human/council picks up)
                ↓
            re-review creates new review_decision row; prior_review_decision_id chains
                ↓
            superseded (when re-review supersedes this one)

Re-review semantics (open decision §9 item 4): each re-review is a NEW row; the prior row stays as historical record. This preserves audit trail per Đ38 manifest-as-code discipline.

7. Routing Model

default_reviewer:
  class: ai
  scope: independent_ai_review_in_separate_execution_context (D2 §4.7)
escalation_triggers (D2 §4.8 risk gating + §4.7):
  - manifest.risk_class = high → reviewer_class must be `human` or `council`
  - vocabulary_gap detected → escalate to Đ24 channel via P0-5 backlog
  - new vocabulary suspected → escalate
  - data loss suspected → escalate
  - legal/governance change → escalate to council
  - any "needs_human" finding in checklist → escalate
reviewer_independence_enforcement:
  rule: reviewer_class='ai' must run in separate execution context from MARK
  evidence: reviewer_independence_evidence JSONB carries process/context fingerprint
  v0.1_enforcement: application-level; FUTURE PG constraint
dot_pair_verifier_co_sign:
  scope: applies to verdicts that gate CUT (verdict=PASS)
  cross_link_p0_3: cut_change_set requires both reviewer PASS + DOT verifier PASS
  populated: cross_signed_by_dot_verifier=true when verifier signs

8. Mapping to governance_event Umbrella (Đ44 Step 3)

governance_event_umbrella_mapping:
  table_design_v0_1: dedicated table `review_decision`
  future_consolidation_option: single `governance_event` table with event_kind discriminator
  forward_compat_field: governance_event_kind=`review_decision` is populated in this design
  rationale_for_dedicated_table_v0_1:
    - clean per-sub-kind ergonomics for v0.1
    - reviewer_identity polymorphism is heavy; dedicated columns clearer
    - Đ44 outcome A.6 #4 leaves umbrella-vs-separate as open follow-up
  if_dieu44_future_chooses_umbrella:
    - migration path: tables can be unified via view or materialized view first
    - then physical consolidation in a separate FUTURE migration phase

9. Open Decisions

1. Schema placement — TAC schema OR new governance/manifest schema. Same decision as P0-2 §9 item 1; joint resolution.
2. verdict enum elevation to Đ24 — currently cutter-local; recommend Đ24 confirmation for vocabulary discipline.
3. reviewer_identity JSONB validation — schema-validated JSONB OR free-form. Recommendation: schema-validated v0.1 via application-layer; PG jsonb_check FUTURE.
4. Re-review handling — new row (chosen) OR version-on-same-row. Recommendation confirmed: new row, prior_review_decision_id chain.
5. Reviewer independence enforcement — application-only OR PG-trigger that compares execution_context_fingerprint with MARK's fingerprint. Recommendation: application v0.1; PG trigger FUTURE.
6. AI vs Human vs Council distinction — single reviewer_class enum (chosen) OR separate columns. Recommendation confirmed: single enum.
7. escalation_ref cardinality — single FK (chosen) OR multiple via junction. Recommendation: single FK + multi-escalation handled by backlog dependency edges (P0-5).
8. findings checklist completeness enforcement — all 10 items required OR partial allowed. Recommendation: all 10 required for verdict=PASS; partial allowed for verdict=FAIL/NEEDS_HUMAN with explicit incomplete-marker.
9. reviewer_identity for human — PII handling — alias only (pseudonymous) per G-5 internal-only default. Recommendation confirmed; named PII via authorization_ref out-of-band.
10. cross_signed_by_dot_verifier semantics — boolean (chosen) OR FK to specific signature record. Recommendation: boolean v0.1 + FK on P0-3 signature record; verifier identity captured in reviewer_identity for the verifier-class row.

10. Dependencies

upstream_dependencies:
  governance:
    - Council Ratification Outcome G-1 (reviewer roles), G-3 (reviewer authority for various intake), G-5 (audience scope for reviewer_identity PII)
    - Đ44 Step 3 governance_event umbrella ratified_with_notes
    - Đ24 Step 1 status/kind/risk_class ratified
    - Đ37 role mapping for reviewer seats
  schema:
    - P0-5 decision_backlog_entry (escalation_ref FK)
    - P0-2 manifest_envelope + manifest_unit_block (review target FK; composite ID for unit-level reviews)
    - P0-1 canonical_address (referenced via manifest_unit_block but not direct FK)
  no_data_dependency_on_p0_3_p0_4: true (P0-3, P0-4 reference P0-6 not vice versa)
downstream_dependents:
  - P0-3 cut_change_set requires verdict=PASS row before CUT
  - P0-4 verify_result cross-references review_decision_id for VERIFY context
  - F2 Health/Correction (D3): review_decision history feeds health signals
  - D11 retrieval: thread/cut audit can cite review_decision_id
operational_dependencies:
  - independent AI review execution context (separate context implementation FUTURE)
  - human reviewer queue routing (Đ37 channel; existing)
  - DOT-pair verifier co-sign mechanism (cross-link P0-3/P0-4 + G-4)

11. Risks

Risk	Severity	Mitigation in this design
AI reviewer not actually independent (same context as MARK)	HIGH (silent override risk)	reviewer_independence_evidence required; FUTURE PG trigger; v0.1 application-layer + audit
findings checklist incomplete on verdict=PASS	Standard	open decision §9 item 8 — enforce all 10 required for PASS
Reviewer identity PII leakage	Standard	pseudonymous alias only; cross-link G-5; authorization_ref out-of-band
Re-review chain cycles	Low	new-row pattern with FK chain; cycles prevented by chain semantics
Verdict drift on re-review without rationale	Standard	rationale recorded in findings; Đ38 versioning audit
cross_signed_by_dot_verifier skipped silently	HIGH (criterion 28 risk)	application-layer enforcement; FUTURE PG constraint via P0-3 FK + check
Escalation_ref pointing to closed/superseded backlog entry	Standard	application-layer validation + backlog status check
reviewer_class='council' quorum not met but verdict recorded	Standard	quorum_count vs quorum_required in reviewer_identity envelope
governance_event_kind value drift if Đ44 future consolidates	Standard	forward-compat field designed; migration path documented
review_duration_ms gameable / inaccurate	Low (advisory)	metric hook only; not authoritative

12. Đ32 Risk Review Notes

proposed_risk_class: Standard
review_inputs_for_dieu32:
  - logical design content (this document)
  - reviewer independence model (§4.2 reviewer_identity envelope)
  - DOT-pair co-sign integration (§7 + cross-link P0-3/P0-4)
  - findings checklist completeness rule (open §9 item 8)
  - PII handling for human reviewer identity (open §9 item 9)
  - cross-law dependencies (Đ24, Đ37, Đ44)
  - migration execution preconditions:
    - P0-5 decision_backlog_entry migrated
    - P0-2 manifest_envelope + manifest_unit_block migrated
    - Đ37 reviewer role table OR canonical role identifier scheme ready
    - composite-FK to manifest_unit_block working post-P0-2
    - backup directus before migration
review_outputs_expected:
  - Đ32 approval / approval_with_notes
  - Đ44 confirmation on umbrella-vs-dedicated table choice (forward-compat path)
  - Đ24 confirmation on verdict enum elevation if recommended
  - PII handling policy ratified with G-5 Access-Control Authority
review_authority: Đ32 council + Đ44 + Đ37 + G-5 (PII) co-sign
review_phase: NOT_STARTED

Special Đ32 attention:

• Reviewer independence is a soft guarantee in v0.1 — application-level only. Đ32 should explicitly accept v0.1's posture OR require PG-level enforcement before approval.
• cross_signed_by_dot_verifier HIGH-risk field — silent omission breaks criterion 28; Đ32 confirm enforcement model.
• Audience scope of reviewer_identity JSONB — internal-only per Decision 3 default; never exposed to Customer/Partner audiences.

13. Explicit Confirmation

no_ddl_written: true
no_sql_written: true
no_create_table_or_alter_table_in_this_document: true
no_column_ddl_in_this_document: true
no_index_ddl: true
no_constraint_ddl_in_this_document: true
no_trigger_or_function_or_rls_policy_written: true
no_migration_executed: true
no_pg_mutation: true
no_qdrant_mutation: true
no_data_writes: true
no_implementation_planning: true
no_existing_file_modified: true
output_form: logical_design_only