C.E.L_Slide_test2/docs/architecture/PHASE-Z-OVERLAY-SCHEMA.md

Phase Z Overlay Schema (Option E first migration)

Status: Step 0 schema lock — pre-execution spec. Scope: F13 / F29 / F16 only (3 active Phase Z frames). Last updated: 2026-05-07.

---

0. Why this doc exists

templates/phase_z2/catalog/frame_contracts.yaml is currently a hand-curated island. It must be hand-edited whenever a Phase Z frame's slot/sub_zone/payload structure changes, even though most of its sibling Phase Z artifacts (V4 matching results, structure_ontology.yaml templates_v1 section, figma_to_html_agent/blocks/{frame_id}/analysis.md) are auto-generated from upstream sources.

Option E first migration converts frame_contracts.yaml to a generated artifact:

runtime_overlay/{template_id}.yaml  (per-template Phase Z fields, hand-edited)
  +
templates_v1[frame_id]              (cross-validation only in first migration)
  ↓
build_phase_z2_frame_contracts.py   (generator)
  ↓
templates/phase_z2/catalog/frame_contracts.yaml  (committed, generated)
  ↓
Phase Z runtime (unchanged — reads frame_contracts.yaml the same way)

This doc locks the schema/keyspace/trigger/rollback rules before any overlay file or generator code is written.

---

0-1. Field owner table

Each field in current frame_contracts.yaml is classified as one of:

• (a) templates_v1-derived — generator looks up from tests/matching/structure_ontology.yaml templates_v1 section. Not declared in overlay.
• (b) overlay-only — Phase Z 전용 operational config. Declared in runtime_overlay/{template_id}.yaml.
• (c) validation duplicate — generator cross-checks overlay value against templates_v1. Disagreement → hard error.

F13 — three_parallel_requirements (frame_id 1171281190)

Field	Current value	Category	Note
template_id	three_parallel_requirements	(c)	overlay filename = template_id; cross-check templates_v1['1171281190'].template_id
frame_id	1171281190	(b)	overlay declares; generator confirms it exists as a templates_v1 key
family	three_parallel	(b)	Phase Z categorization. Not the same as templates_v1.visual_pattern.family (= list) — different semantic axis. Name overlap is incidental.
source_shape	top_bullets	(b)	Phase Z B1 extractor signal. Not in templates_v1.
cardinality.strict	3	(c)	cross-check against templates_v1.visual_pattern.cardinality — must equal min (and max if min==max).
cardinality.overflow_policy	abort_or_review	(b)	Phase Z fallback policy.
role_order	[tech, people, nature]	(b)	F13-specific visual role mapping. Not in templates_v1.
visual_hints.min_height_px	230	(b)	Phase Z layout calculation. Not in templates_v1.
accepted_content_types	[text_block]	(b)	SPEC v1 §3 Layer A→B input. Not in templates_v1.
sub_zones	[pillar_1, pillar_2, pillar_3] (with partial_target_path)	(b)	Phase Z Frame Slot declaration. Conceptually overlaps with templates_v1.slots (pillar_*_label/body) but different shape (sub_zones = column units; slots = label+body pairs).
payload.*	{title, builder, builder_options}	(b)	Phase Z mapper directives. Not in templates_v1.

F29 — process_product_two_way (frame_id 1171281210)

Field	Current value	Category	Note
template_id	process_product_two_way	(c)	filename = template_id; cross-check
frame_id	1171281210	(b)
family	two_column_h3	(b)	templates_v1.visual_pattern.family = compare; intentionally different
source_shape	h3_subsections	(b)	F29-specific B1 path
cardinality.strict	2	(c)	cross-check against templates_v1.visual_pattern.cardinality.{ideal:2, min:2, max:2}
cardinality.overflow_policy	abort_or_review	(b)
visual_hints.min_height_px	345	(b)
accepted_content_types	[text_block, transform_table]	(b)	F29 process column accepts AS-IS/TO-BE table
sub_zones	[process_column, product_column] (each cardinality.strict: 3)	(b)	2 column × 3 sections; sub_zone unit = column
payload.*	{title, builder=process_product_pair, builder_options}	(b)

F16 — bim_issues_quadrant_four (frame_id 1171281193)

Field	Current value	Category	Note
template_id	bim_issues_quadrant_four	(c)
frame_id	1171281193	(b)
family	bim_issues_quadrant	(b)	templates_v1.visual_pattern.family = cards
source_shape	top_bullets	(b)
cardinality.strict	(not declared)	n/a	F16 intentionally omits — uses pad_to=4 + truncate>4 policy in payload.builder_options. templates_v1.cardinality has {ideal:4, min:4, max:4} but Phase Z does not enforce strict here. Generator must NOT auto-derive this from templates_v1.
accepted_content_types	[text_block]	(b)
sub_zones	[quadrant_1, quadrant_2, quadrant_3, quadrant_4] (each cardinality.strict: 1)	(b)	sub_zone-level cardinality = capacity; not the same as frame-level
payload.*	{title, builder=quadrant_flat_slots, builder_options.{item_parser, pad_to, truncate_at, label_key_pattern, body_key_pattern, empty_label, empty_body}}	(b)

Summary

• (a) templates_v1-derived: none in first migration. Overlay declares all operational config.
• (b) overlay-only: ~all fields. Overlay file is essentially a per-template extract of the current frame_contracts.yaml entry.
• (c) validation duplicate: 2 fields per template — template_id (overlay filename matches templates_v1[frame_id].template_id) and cardinality.strict when present (must match templates_v1.visual_pattern.cardinality.min).

Implication: first migration is mostly a split-and-concatenate refactor with light cross-validation. Migration value is (i) per-template editing isolation, (ii) templates_v1 consistency check at build time. Heavier derivation (e.g., generating cardinality.strict from templates_v1 automatically) is 별 axis — defer until a concrete need surfaces.

---

0-2. Duplicate rule — hard error

If an overlay file declares a field that is classified as (a) templates_v1-derived, generator fails immediately with a clear message. No silent override semantics.

Currently no fields are in (a), so this rule is dormant for first migration. It exists to prevent regression: a future overlay author cannot quietly duplicate a templates_v1-owned field without removing the (a) classification first.

For (c) validation duplicate fields, the rule is:

• Overlay declares the value.
• Generator looks up the corresponding value in templates_v1.
• If the two disagree, hard error with both values printed and a pointer to this doc.

This preserves the lock-layer "overlay = single source of truth for declared values" while making templates_v1 drift visible.

---

0-3. Keyspace rule

• Source ref = frame_id (Figma origin).
• Overlay identity = template_id (filename: runtime_overlay/{template_id}.yaml).
• First-migration assumption: frame_id ↔ template_id is 1:1 for all active Phase Z frames (F13/F29/F16).
• Generator verification: for each overlay, the generator looks up templates_v1[overlay.frame_id].template_id and asserts it equals the overlay filename's {template_id}. Mismatch → hard error.
• Multi-variant (one frame ↔ multiple templates) = 별 axis. When that case appears, this doc is updated and the keyspace becomes a composite key. Until then, 1:1 is locked.

---

0-4. Trigger

• Manual run for first migration:

  python scripts/build_phase_z2_frame_contracts.py
  

• Verification (semantic-identical) is required after each run. Generator should refuse to write output if the result differs semantically from current frame_contracts.yaml during first migration.
• CI / pre-commit automation = 별 axis. Will be considered after first migration ships and a drift incident actually occurs. Adding it now is over-engineering for 3 templates.

---

0-5. Rollback / failure path

If semantic-identical verification fails (yaml.safe_load(current) != yaml.safe_load(generated)):

1. Generated artifact is NOT adopted. No write to frame_contracts.yaml.
2. Current frame_contracts.yaml remains canonical (status quo preserved).
3. Diff source: overlay schema, generator implementation, or templates_v1 cross-check rule. Identify root cause.
4. Fix overlay/schema/generator. Retry from Step 1.
5. Migration is incomplete: 3 active templates partially migrated count as failure — either all 3 ship or none.

The migration commit (Step 5) is only made after all 3 templates pass both (a) semantic-identical and (b) Phase Z runtime regression (final.html identical).

---

0-6. Scope boundary

Option E first migration solves:

• frame_contracts.yaml island problem (hand-curated → generated).
• Per-template editing isolation.
• Light templates_v1 consistency check at build time.

Option E first migration does NOT solve (= 별 axis, NOT addressed by this migration):

• analysis.md ↔ structure_ontology.yaml ownership direction conflict. Specifically: figma_to_html_agent/CLAUDE.md implies forward direction (agent owns analysis.md), while tests/matching/sync_analysis_from_ontology.py enforces reverse direction (structure_ontology.yaml is source, analysis.md is mirror). This is a separate architectural decision and is out of scope here.
• templates/blocks/structures legacy retirement.
• legacy templates/catalog/blocks.yaml removal.
• zone_extract rule formalization (long-term zone_application policy).
• 32-frame full audit (only active F13/F29/F16 in first migration).

When the user resumes work on the direction inversion axis, this doc is not invalidated — overlay schema and generator continue to work because they read templates_v1 (not analysis.md).

---

Migration steps (post-Step 0)

1. Create templates/phase_z2/catalog/runtime_overlay/{F13,F29,F16}.yaml files. Each contains the (b) overlay-only fields + (c) validation duplicate values for one template.
2. Write scripts/build_phase_z2_frame_contracts.py generator. Reads overlays + templates_v1, applies 0-2 / 0-3 rules, writes generated frame_contracts.yaml.
3. Run generator. Verify yaml.safe_load(current) == yaml.safe_load(generated). List order preserved (sub_zones especially). On disagreement → 0-5 rollback.
4. Run Phase Z pipeline once (regression MDX) — confirm final.html is byte-identical to current run.
5. Commit Option E migration (overlay files + generator + new generated frame_contracts.yaml with header). Separate commit from Step 0 schema doc.

---

Out of scope for this doc

• Generator implementation details (parsing, emit format, error message templates) — captured in the script itself.
• Overlay file format details beyond field categorization — captured in the overlay files themselves.
• Direction inversion fixes — see future axis docs.