Skip to content

Cross-Cutting Review R5

Verdict: NOT SHIP

Summary

The three documents now align on the intended definitions in their glossary / terminology sections, and the canonical YAML format is also aligned. However, Tier 3 still contains several downstream UI and workflow sections that reintroduce Area as a separate concept from Zone, which creates a remaining cross-tier contradiction.

Verification

1) Area vs Zone definitions

Aligned in the key terminology sections:

  • Tier 1 defines Zone as the formal grouping concept and Area as either:
  • runtime admin API projection (area_id / area_name), or
  • Tier 2 bundle-document terminology
    (tier1-yaml-first-authoring.md:23-26)
  • Tier 2 matches that exactly:
  • Area (runtime) = admin API label
  • Area (Tier 2 generation) = bundle document
  • Zone = formal world-grouping stored on the room zone field
    (tier2-ai-content-pipeline.md:690-700)
  • Tier 3 glossary also matches:
  • Zone = formal world-grouping
  • Area = API-layer naming only, underlying concept is zone
    (tier3-visual-tools.md:21-22)

But Tier 3 still contradicts its own glossary later on. Examples:

  • Separate filters shown for both Zone and Area in the same UI mockup
    (tier3-visual-tools.md:905-906)
  • New-room dialog uses Area as if it were the assignable grouping field
    (tier3-visual-tools.md:980-983)
  • Bulk actions include both Set Zone and Set Area
    (tier3-visual-tools.md:1015-1016)
  • Inspector header shows distinct values for Zone and Area
    (tier3-visual-tools.md:1317-1318)
  • Data grid toolbar again exposes both Zone and Area filters
    (tier3-visual-tools.md:2170)

Those sections imply Area is a second formal grouping dimension, which conflicts with:

  • Tier 1 terminology
  • Tier 2 terminology note
  • Tier 3 glossary
  • Tier 3 area_id annotations stating area_id maps to zone assignment
    (tier3-visual-tools.md:376-377, 391-392, 937, 1054)

2) Canonical format consistency

This is now consistent enough across tiers:

  • Tier 1: canonical interchange/storage format is component-centric YAML with _meta.schema and components:, with room-specific allowed top-level exits and zone
    (tier1-yaml-first-authoring.md:162-175)
  • Tier 2: AI output uses the same loader-compatible shape and explicitly calls out room extras exits and zone
    (tier2-ai-content-pipeline.md:199-214)
  • Tier 3: visual-editor export/import is described as Tier 1 loader-compatible, using _meta.schema, components:, and top-level exits / zone for rooms
    (tier3-visual-tools.md:1073-1214)

So on format, the docs are aligned.

3) New cross-tier contradictions

Yes — there is still a remaining contradiction, localized to Tier 3 UI/workflow language:

  • the glossary says Area is only API naming over zone assignment,
  • but multiple later Tier 3 sections still present Area as an independent editable/filterable domain concept.

Final assessment

The core terminology sections are fixed, and the canonical format is aligned.
But the review should not ship yet, because Tier 3 still contains visible contradictory usages that would confuse readers about whether Area is:

  1. just API naming for zone assignment, or
  2. a second formal grouping concept alongside Zone.

Required cleanup before ship

Update Tier 3 stale references that still treat Area as separate from Zone, especially:

  • tier3-visual-tools.md:905-906
  • tier3-visual-tools.md:980-983
  • tier3-visual-tools.md:1015-1016
  • tier3-visual-tools.md:1317-1318
  • tier3-visual-tools.md:2170