Skip to content

Cross-Cutting Review R4

Verdict

NOT SHIP

The R3 fixes materially improved the suite, but the full three-tier set still does not clear the bar because Area vs Zone terminology is not fully standardized across the docs. Checks 2 and 9 fail; the rest pass.

Summary Table

Check Result Notes
1. Canonical format agreement PASS All three tiers align on component-centric YAML with _meta.schema, with room-specific exits/zone allowance.
2. Area vs Zone consistency FAIL Tier 1, Tier 2, and Tier 3 each give Area a different meaning.
3. No _schema anywhere PASS No YAML _schema field found in any tier doc.
4. CLI namespaces conflict PASS maid data, maid ai, @ai, and existing builder/admin namespaces remain distinct.
5. Tier dependencies clear and non-circular PASS Tier 2 depends on Tier 1; Tier 3 depends on Tier 1 and only optionally integrates with Tier 2.
6. Source of truth consistent PASS YAML is canonical for repeatable content; live world is authoritative at runtime; export is explicit.
7. WebSocket conventions consistent PASS Tier 3 consistently uses /admin/ws plus additive editor/world channels and lowercase underscore message types.
8. Balance analysis ownership clear PASS Tier 2 owns analysis engine; Tier 3 owns presentation/dashboard layer.
9. Terminology standardized FAIL The overloaded use of Area remains a cross-doc terminology hazard.

Findings

1) Canonical format agreement — PASS

The three docs now align on the cross-tier canonical format contract:

  • Tier 1 defines canonical format as machine-readable, component-centric YAML using _meta.schema and components: (tier1-yaml-first-authoring.md:25, tier1-yaml-first-authoring.md:162-167).
  • Tier 1 also explicitly states that rooms may use top-level exits and zone alongside components: (tier1-yaml-first-authoring.md:169-175).
  • Tier 1 standardizes schema declaration under _meta.schema (tier1-yaml-first-authoring.md:1104-1113).
  • Tier 2 says its output stays loader-compatible and uses _meta.schema, with room-specific top-level exits and zone allowed (tier2-ai-content-pipeline.md:199-210).
  • Tier 3 says visual-editor export uses Tier 1 loader-compatible shape, explicitly including top-level exits and zone, while distinguishing that from @export's smaller component-only shape (tier3-visual-tools.md:1078-1081, tier3-visual-tools.md:1100-1103, tier3-visual-tools.md:1189-1193, tier3-visual-tools.md:1208-1210).

2) Area vs Zone consistency — FAIL

The claimed distinction exists, but it is not consistent across all three tiers:

  • Tier 1: Zone is formal; Area is an informal synonym for Zone (tier1-yaml-first-authoring.md:23-24).
  • Tier 2: Area means a multi-entity bundle document, while zone is the formal world grouping (tier2-ai-content-pipeline.md:688-700, tier2-ai-content-pipeline.md:4864-4868).
  • Tier 3: Zone is formal, but Area is described as a legacy room metadata label (tier3-visual-tools.md:21-22).
  • Tier 3 still exposes separate zoneId and areaId filters in the editor model, reinforcing Area as a separate concept in practice (tier3-visual-tools.md:1051-1055).
  • Tier 3 also uses “Area” widely in UI/UX language (Area: field, Set Area, Area-Clustered) (tier3-visual-tools.md:982, tier3-visual-tools.md:1015-1016, tier3-visual-tools.md:1240-1247).

This means Area simultaneously means: 1. a synonym for Zone, 2. a bundle document, 3. a legacy room metadata field.

That is not standardized enough for a clean cross-tier contract.

3) No _schema anywhere — PASS

I found no YAML field usage of _schema in any of the three tier docs. Searches for _schema: returned no matches. The only _schema hits were Tier 2 internal Python identifiers like self._schema / json_schema, not YAML document shape (tier2-ai-content-pipeline.md:84, tier2-ai-content-pipeline.md:1584, tier2-ai-content-pipeline.md:1607).

4) CLI namespaces don't conflict — PASS

The namespace split is clear:

  • Tier 1: maid data ... (tier1-yaml-first-authoring.md:4053-4069).
  • Tier 2: maid ai ... and @ai ... (tier2-ai-content-pipeline.md:349, tier2-ai-content-pipeline.md:725, tier2-ai-content-pipeline.md:785, tier2-ai-content-pipeline.md:838, tier2-ai-content-pipeline.md:882, tier2-ai-content-pipeline.md:943, tier2-ai-content-pipeline.md:992, tier2-ai-content-pipeline.md:1014, tier2-ai-content-pipeline.md:1047, tier2-ai-content-pipeline.md:1093, tier2-ai-content-pipeline.md:3829-3952).
  • Tier 3: existing builder/admin surfaces and references to existing commands (@create, @dig, @zone, @export) plus Tier 1 commands for import/export flows (tier3-visual-tools.md:71, tier3-visual-tools.md:74, tier3-visual-tools.md:166, tier3-visual-tools.md:214, tier3-visual-tools.md:3027).

I did not find a cross-tier command-name collision.

5) Tier dependencies clear and non-circular — PASS

  • Tier 2 explicitly depends on Tier 1 (tier2-ai-content-pipeline.md:1-7).
  • Tier 3 explicitly depends on Tier 1 and only optionally integrates with Tier 2 (tier3-visual-tools.md:7-8, tier3-visual-tools.md:3325-3345).
  • Tier 2 routes generated output through Tier 1 validation/pipeline rather than the reverse (tier2-ai-content-pipeline.md:197-199, tier2-ai-content-pipeline.md:228, tier2-ai-content-pipeline.md:235-243).

I do not see a circular dependency between tiers.

6) Source of truth consistent — PASS

The ownership model is now coherent across the suite:

  • Tier 1: YAML files are the source of truth for content loaded through the pipeline; world-to-YAML is explicit export (tier1-yaml-first-authoring.md:149-167).
  • Tier 3: YAML is canonical for repeatable content, but the live world is authoritative at runtime; visual editor changes do not automatically rewrite YAML (tier3-visual-tools.md:147-166).
  • Tier 2: @ai.accept affects live state only; canonical YAML requires explicit export (tier2-ai-content-pipeline.md:3874-3878).

This is consistent and believable.

7) WebSocket conventions consistent — PASS

Only Tier 3 defines the WebSocket contract, and it does so consistently:

  • Baseline is still WS /admin/ws (tier3-visual-tools.md:71, tier3-visual-tools.md:628-634).
  • Proposed additive channels are editor and world (tier3-visual-tools.md:638-675).
  • Client/server protocol examples consistently use lowercase underscore message types such as editor_cursor, editor_lock_acquire, room_created (tier3-visual-tools.md:744-765, tier3-visual-tools.md:3392-3396, tier3-visual-tools.md:3401-3416, tier3-visual-tools.md:3488-3523).

I found no cross-tier contradiction here.

8) Balance analysis ownership clear — PASS

The ownership split is explicit:

  • Tier 2 defines the balance analysis engine (tier2-ai-content-pipeline.md:3213-3224).
  • Tier 3 states that the Balance Dashboard is a presentation layer over Tier 2's engine, with graceful degradation if Tier 2 analysis is absent (tier3-visual-tools.md:2307-2315, tier3-visual-tools.md:3333-3340).

This boundary is clear.

9) Terminology standardized — FAIL

The docs are improved, but the terminology is still not standardized enough for a final cross-cutting sign-off because Area is overloaded differently by each tier. The glossary-level fix did not fully converge the suite:

  • Tier 1: Area = informal synonym for Zone (tier1-yaml-first-authoring.md:23-24).
  • Tier 2: Area = multi-entity bundle document (tier2-ai-content-pipeline.md:690-700).
  • Tier 3: Area = legacy room metadata label (tier3-visual-tools.md:21-22).

This is the same root issue as Check 2, but it also affects the broader terminology standardization question.

Final Recommendation

Do not mark this review round as SHIP yet.

The suite is close. To clear the bar, pick one cross-tier policy for Area and apply it everywhere, for example:

  • reserve Zone for the formal world-grouping concept,
  • reserve Area for exactly one other meaning (or eliminate it entirely from new prose),
  • rename Tier 2's “area generation” bundle terminology if necessary,
  • scrub Tier 3 UI/UX language so any remaining areaId/area_name references are explicitly marked legacy/API-only.