Skip to content

Tier 1 YAML-First Authoring — Round 3 Review

Verdict

Not SHIP yet.

Round 2 fixes are largely real and verifiable in the document/code pair. I re-checked all 11 requested R2 items and they appear fixed:

  1. DataDrivenContentPack is explicitly marked ⚠️ PROPOSED and not presented as current.
  2. Assembly Layer is explicitly marked ⚠️ PROPOSED, with current component-centric format shown.
  3. LoaderContext / pack extras correctly notes the @dataclass(slots=True) limitation.
  4. semantic_rules is documented as custom rules only; PreparePhase prepends BUILTIN_RULES.
  5. Non-core entity types are marked as pack-provided, not engine-standard.
  6. _schema → _meta.schema cleanup appears applied.
  7. Component field shape fixes called out in R2 are reflected in the doc.
  8. Rule suppression is moved to future work and current built-in rule IDs are real.
  9. Source-of-truth component descriptions are mostly aligned to the real models.
  10. @ref: dependency is documented as recommended, not enforced.
  11. Canonical format is explicitly defined as component-centric.

Remaining issues

HIGH — §3 / §7 present proposed CLI commands as current behavior

What’s wrong: Several non-proposed sections describe commands that do not exist in the codebase as if they are part of the current workflow: - maid data export is treated as the current “World → YAML” operation and canonical interchange path (tier1-yaml-first-authoring.md:24, 156-164, 225-226). - maid data diff is described as a current reconciliation mechanism (199-205, 212-214). - maid data watch / maid data schema export-refs are described as active regeneration workflow in §7.5 (2600-2607).

But the actual CLI only defines validate, lint, preview, load, resolve, reload, unload, and schema list/show under maid data (packages/maid-engine/src/maid_engine/cli/app.py:2827-3145). There is no data diff, data export, data watch, or data schema export-refs command.

Fix: In §§3 and 7, mark these as proposed future commands (or rephrase current-state claims around the existing @export builder command only).

HIGH — §5.6 proposes assembly_rule on EntityTypeConfig, but that field does not exist

What’s wrong: §5.6 says custom assembly rules can be registered via custom_entity_type_configs() by attaching an optional assembly_rule to each EntityTypeConfig (tier1-yaml-first-authoring.md:1078-1082).

Actual EntityTypeConfig has only: - type_name - required_components - default_components - default_tags - allowed_top_level_fields

See packages/maid-engine/src/maid_engine/loader/models.py:137-145.

Fix: Either add a separate proposed hook/mechanism for assembly rules, or clearly mark assembly_rule as a new field that must be added to EntityTypeConfig before this design works.

HIGH — §6.3 NPC example still contains invalid autonomy enum values

What’s wrong: The NPC example is still not source-of-truth accurate for the real autonomy models: - activity: idle is used in schedule blocks (tier1-yaml-first-authoring.md:1489-1512), but ActivityType does not include idle; valid values are work, sleep, eat, socialize, patrol, guard, trade, craft, worship, train, wander, custom (packages/maid-stdlib/src/maid_stdlib/models/npc/autonomy.py:50-64). - NeedsComponent example uses hunger, rest, social, duty as categories (1518-1534), but NeedCategory is survival, economic, purpose, comfort (autonomy.py:18-24). - source: event is used in GoalsComponent (1546-1548), but GoalSource is innate, derived, reactive, social, quest (autonomy.py:40-47).

These examples would not validate against the real models.

Fix: Replace the example enum values with real ones from maid_stdlib.models.npc.autonomy.

MEDIUM — §6.5–§6.11 still show author-friendly examples without the same Assembly Layer warning/current-format pairing

What’s wrong: The doc carefully warns that §6.2–§6.4 examples are author-friendly and require the proposed Assembly Layer (tier1-yaml-first-authoring.md:1158-1161). But the later pack-provided/template examples in §6.5–§6.11 also use author-friendly top-level fields like name, npc, stats, health, combat, etc. (1706-1785, 2134-2208) without the same warning or a component-centric equivalent.

Current PreparePhase reads components directly and there is no Assembly Layer today (packages/maid-engine/src/maid_engine/loader/phases/prepare.py:139-172; §5 already states Assembly is not implemented). So these later examples are also not loadable as-written in the current codebase.

Fix: Extend the format note to cover §6.5–§6.11 as well, or show current loadable component-centric versions alongside those examples.