aetherbound-guild/docs/reviews/DESIGN_VALIDATION_CONTRACT.md

Pre-development Design Validation Contract

Contract revision: abg-design-validation-v2-crossdoc-r6-region-art Frozen input: .agent-taskgraph/spec.md revision design-spec-r3 Integrated schema evidence: 8102bd2 Executable: tools/validate_predevelopment_design.py Scope: merged Markdown design authorities plus one scoped reference gate; no runtime or product authority

1. Purpose And Boundary

This contract defines deterministic checks for the merged product, content, UX, art, and audio design package. It detects mechanical omissions before independent review without choosing product values or changing another workstream's schema.

The executable answers thirteen bounded questions:

1. Do the primary catalogs contain the exact frozen content envelope with unique, gap-free stable IDs and nonempty rows?
2. Do references to registered IDs and declared presentation bindings resolve?
3. Are integration placeholders still unresolved?
4. Does an authority positively prescribe a retired redesign concept?
5. Are the required page, art, music, ambience, SFX, and voice registries structurally complete?
6. Does the stable-screen and onboarding presentation preserve the product's provisional selected/offered values and pre-creation revision boundary?
7. Do UI and art assign the same exposed/protected party endpoints to left and right?
8. Does every generated-recruit presentation field have an exact, deterministic content/art crosswalk?
9. Does audio bind the exact primary screen-ID set, including OUT-006, and declare the matching total?
10. Does the scoped reference authority reject rather than prescribe retired fixed-cast and relationship scope?
11. Is one Run seed durably reserved and read back before opening generation, with all four offers, a revisable pair, and atomic exactly-once promotion bound to that one draft?
12. Does every hidden-profession art row bind the exact content-owned identity, parents, mechanic, silhouette/prop brief, VFX cue, and action language without a deferred content pointer?
13. Does every ART-REG-01..08 row bind the same-ordinal RG-01..08 exactly once, with the exact region name and content-compatible biome/landmark, palette/material, and hazard/mechanic briefs?

Passing is necessary but not sufficient. The validator cannot establish originality, balance, comprehension, readability, production feasibility, listening quality, fun, or owner acceptance.

2. Authority Input

The validator reads UTF-8 Markdown recursively from:

• docs/product/
• docs/content/
• docs/presentation/

These files must exist:

• docs/product/GAME_PRODUCT_CONTRACT.md
• docs/product/SYSTEMS_AND_BATTLE.md
• docs/product/ECONOMY_AND_BALANCE.md
• docs/product/SAVE_AND_FAILURE_CONTRACT.md
• docs/content/RECRUIT_GENERATION.md
• docs/presentation/SCREEN_AND_STATE_MAP.md
• docs/presentation/UI_AND_VISUAL_SYSTEM.md
• docs/presentation/ART_ASSET_AND_ANIMATION_CATALOG.md
• docs/presentation/AUDIO_MUSIC_AND_VOICE_CATALOG.md

docs/content/CHARACTER_BIBLE.md is a retired fixed-character authority and must not exist. Reference research, reviews, prototypes, and taskgraph files are outside the ordinary authority scan. The sole exception is the targeted retired-scope scan of docs/reference/TRANSFERABLE_STRUCTURE_LESSONS.md; its IDs, ranges, and other research statements do not enter product/content registry validation.

3. Primary Content Registries

3.1 Definition Ownership

An ID is a definition only in its canonical primary table. A topology audit, assignment summary, coverage table, or cross-reference table remains a reference even when its first cell contains the ID. This distinction prevents reference coverage from being mistaken for duplicate content.

Family	Primary owner/table	Stable IDs	Exact count
Base professions	PROFESSION_CATALOG.md, Base Professions	PF-B01..PF-B12	12
Advanced professions	same, Regular Advanced Professions	PF-A01..PF-A24	24
Hidden hybrids	same, Hidden Hybrid Professions	PF-H01..PF-H06	6
Traits	TRAIT_CATALOG.md	TR-001..TR-036	36
Equipment	EQUIPMENT_CATALOG.md	EQ-001..EQ-320	320
Artifacts	ARTIFACT_CATALOG.md	AR-001..AR-060	60
Ordinary/elite enemies	ENEMY_CATALOG.md identity tables	EN-Rr-nn	100
Bosses	ENEMY_CATALOG.md boss table	BO-R1-01..BO-R8-02	16
Regions	REGION_CATALOG.md, Region Matrix	RG-01..RG-08	8

The validator binds to these integrated stable schemas. It does not alias them to the obsolete PR-*, EN-O*, EN-B*, or REG-* assumptions.

Ordinary/elite enemy IDs must use regions 1..8. The combined count is 100; each region must be nonempty and its ordinal sequence must be gap-free from 01. The validator does not choose the region distribution. Boss IDs are the integrated two-per-region set declared by the content authority.

3.2 Row And Duplicate Gate

Every primary row must have the complete structural column count of its owner table. Required cells must be nonempty and may not contain TBD, TBC, TODO, FIXME, or a placeholder. Repeating a primary definition is an exact duplicate error. A missing ordinal is both a count/set failure and, for the regional enemy schema, a sequence-gap failure.

The validator proves structural presence, not that prose changes a meaningful decision. The independent reviewer still owns the qualitative no-filler gate.

4. References And Compact Ranges

Registered numeric references are checked across all authority documents. Supported bounded forms include:

PF-B01..PF-B12
EN-R1-01..EN-R1-12
ART-PRO-B01..B12
MUS-R01..08-BATTLE
AMB-G01..G12
AMB-R{01..08}-01..08
PRO-001..PST-003

The right endpoint may repeat the full prefix, abbreviate the trailing fixed prefix, or omit it. A suffix after the right number applies to every expanded member. One numeric brace range creates a bounded Cartesian expansion. A mixed-prefix range validates its two explicit endpoints without inventing an ordering between namespaces.

Compatible numeric ranges must be ascending and expand to at most 1,001 IDs. Malformed or unbounded uppercase hyphenated ID ranges fail. Numeric formulas, decimal ellipses, CONTENT.*[01..n] binding paths, and lowercase save-slot ranges are not stable-ID expressions and are ignored by the ID parser.

5. Integration Bindings

5.1 Declared Presentation Interfaces

BIND:* is a declared design interface, not a value placeholder. Its canonical declaration is a first-cell row in the binding registries of SCREEN_AND_STATE_MAP.md or UI_AND_VISUAL_SYSTEM.md. Every BIND:* reference must resolve to exactly one declaration with a use and owner/source. Unknown or duplicate binding declarations fail.

5.2 Unresolved Values

Uppercase bracket names such as [SUPPORTED_VOICE_LOCALES] are unresolved integration values. The validator reports each unique bracket binding once at its first occurrence. It also rejects:

• TBD, TBC, TODO, and FIXME
• double-brace placeholders such as {{BINDING:deployment_capacity}}
• named forms beginning with BINDING:, BINDING(, or BINDING[

BINDING_UNRESOLVED never supplies a fallback or assumes which authority was intended. The owning authority must resolve or explicitly redesign the interface.

6. Retired Concepts

Positive authority fails for:

• fixed cast, fixed named protagonists, or 30 authored heroes
• relationship scenes/systems, affinity systems, romance, or personal arcs
• a fixed six-unit deployment rule
• a three-lane grid or spatial three-band grid/formation
• capitalized battle/economy concepts Directive, Anchor, and Cache
• manual skill activation or in-battle intervention commands

Explicit negation, removal, migration, history, and negative rg/grep acceptance commands are documentary contexts rather than positive authority. The exemption is local to the line. three-band cadence alternation is a time grammar, not the retired spatial grid; it is not rejected. Positive three-lane or spatial three-band language still fails.

7. Presentation Coverage

7.1 Screens

SCREEN_AND_STATE_MAP.md defines stable page rows ending in three digits. Each row requires ID, page/state, landscape composition or focal structure, primary action, and state/exit behavior. At least one row must cover:

• shop/offers
• recruit/hire
• equipment/loadout
• party-line formation/reorder
• automatic battle
• result/reward/diagnosis
• failure/death/recovery
• save/cloud continuation
• settings/controls
• accessibility
• localization/language
• endgame/postgame/mastery

The authority as a whole must cover landscape, empty, error, confirmation, input, localization, and accessibility behavior.

7.2 Art, Animation, And VFX

The art authority must expand to these exact production ID sets:

Family	Stable art IDs	Count
Profession kits	ART-PRO-B01..B12, ART-PRO-A01..A24, ART-PRO-H01..H06	42
Trait presentation	ART-TRT-01..36	36
Equipment presentation	ART-EQP-001..320	320
Artifact presentation	ART-AFT-01..60	60
Ordinary/elite enemies	ART-ENM-001..100	100
Bosses	ART-BOS-01..16	16
Regions	ART-REG-01..08	8

It must also name modular generated recruits, equipment readability, an animation matrix, VFX/visual-effects language, and landscape composition.

7.3 Music, Ambience, SFX, And Voice

The audio authority uses several canonical definition forms: music suite rows, ambience configuration ranges in the second table cell, fenced voice/SFX ledgers, and the regional SFX table. They expand to:

Registry	Exact identities
Music suites	32
Ambience configurations	76
Shared SFX events	228
Semantic voice intents	32

Every expected ID must appear exactly once. The document must cover shop, recruitment, equipment, order, battle, pause, speed, inspect events, retreat, casualty, dismissal, reward, failure, accessibility, and generated-recruit voice scope. Underscore event names such as inspect_open count as explicit inspection coverage.

8. Cross-Document Semantic Gates

8.1 Provisional Opening Choice

The product authority supplies the selected and offered cardinalities; the validator does not duplicate them as fallback constants. Every positive provisional-choice declaration in the product contract must resolve to one consistent pair. A primary stable-screen row must expose the same offer and selection counts plus the revisable pre-creation boundary. Onboarding may keep those facts in one row or split them across staged rows only when every row is bound to that same primary screen ID. Counts in invalid-state prose, such as zero/one/three/four selected or two unchosen offers, are not affirmative values.

8.2 Party Direction

UI_AND_VISUAL_SYSTEM.md owns the left/right placement of exposed-front and protected-rear endpoints; First exposed and Last are accepted equivalent endpoint labels. ART_ASSET_AND_ANIMATION_CATALOG.md must independently declare the same endpoints. The validator accepts endpoint-before-side, screen-left is .../screen-right is ..., and cross-line left-to-right declarations, normalizes each to (left endpoint, right endpoint), and requires exact equality. Naming both concepts without direction is insufficient.

8.3 Recruit Content/Art Crosswalk

The required generated-recruit fields and option counts come from the fenced Recruit Record and the Modular Visual Grammar table in RECRUIT_GENERATION.md. Art must provide a Recruit Content/Art Crosswalk table that supplies these semantic values:

Column	Required value
Content field	exact snake-case Recruit Record field
Content cardinality	exact count in a dedicated column or in a stored-authority cell
Art binding	declared source library, bounded stable-ID range, or explicit nonvisual owner
Art cardinality	explicit count or bounded range cardinality matching content and the source inventory
Deterministic resolution	explicit rule, equal bounded endpoints, or one exact profession package binding

The ten required rows are body_frame, face_shape, skin_palette, hair_shape, hair_palette, garment_cut, garment_palette, profession_overlay, detail_mark, and voice_effort_set. Each visual row's count must also equal the matching source inventory declaration. The voice row must explicitly identify audio ownership or a nonvisual disposition. Both a dedicated five-column count/mapping table and the integrated four-column Recruit record field | Stored authority | Art binding | Derived assembly shape are valid when they carry the same semantics. A prose claim that generation is deterministic cannot replace this field-level table.

8.4 Screen/Audio Identity

Primary screen rows in SCREEN_AND_STATE_MAP.md are the canonical set. That set must include OUT-006. The audio dependency row named Screen and action IDs must expand to exactly the same set, with neither omissions nor additions, and its declared screen total must equal the canonical set size. A matching count with a different ID set still fails.

8.5 Scoped Reference Retirement

TRANSFERABLE_STRUCTURE_LESSONS.md may discuss fixed-cast or relationship concepts only as explicit rejection, removal, or historical/reference evidence. Positive profession affinities, relationship hook/system, fixed cast, or an approved exact scope of 30 named recruitable characters fails. Markdown table cells are evaluated separately so a filler-rejection cell does not negate a positive requirement in another cell on the same row.

8.6 Seed-First Run-Creation Transaction

SAVE_AND_FAILURE_CONTRACT.md owns the durable transaction. Its seed-first section must place an applied, persisted or read-back Run seed/draft boundary before opening generation. RECRUIT_GENERATION.md must independently restrict opening generation to that validated read-back draft created by seed reservation. A seed that exists only inside current_run, or one persisted after generation, fails RUN_CREATION_SEED_ORDER_MISMATCH.

The save schema must declare run_creation_draft with one seed, the exact four-offer set, the exact two-offer selection and its revision, mutually exclusive with current_run. The transaction table must semantically bind four operations: reserve a seed-only draft, materialize all four indexed offer records/IDs/hashes, persist a revisable exact pair over those same four, and promote the same seed and selected records while removing the draft. The detailed flow must also establish one-commit offer materialization, revision without regeneration, atomic promotion, and retry resolution to the original applied receipt without a second Run or second transfer.

These checks accept equivalent wording such as persisted/durable, read-back, all-or-nothing/atomic, original/one applied receipt, and no/cannot create a second Run. They do not match a repaired sentence byte-for-byte. Missing schema, table, revision, materialization, promotion, or retry evidence fails RUN_CREATION_TRANSACTION_INCOMPLETE.

8.7 Hidden-Profession Content/Art Binding

PROFESSION_CATALOG.md owns PF-H01..PF-H06, each name, exact two-base parent set, core mechanic and comma-delimited production brief. The validator derives those values from the Hidden Hybrid Professions table; it does not keep a second hard-coded parent or mechanic map.

The matching Hidden Hybrid Profession Kits table in ART_ASSET_AND_ANIMATION_CATALOG.md must provide, for every ID:

• the exact ART-PRO-Hxx, CONTENT.PROFESSION.HIDDEN[xx], PF-Hxx and name;
• the same two PF-Bxx parents as content;
• resolved silhouette translation and held/worn prop or anchor fields;
• resolved VFX/event-cue and animation/action-verb fields;
• semantic overlap between the content mechanic and art translation, and between each content production channel and its art field.

Comparison removes Markdown emphasis, case, plural and common inflection differences, then ignores generic connective vocabulary. This permits independently written production language while still rejecting an unrelated bow/vial, hammer/lantern, or other mechanic package. Missing identities, parents, fields, or mechanic-compatible channel bindings fail HIDDEN_PROFESSION_ART_MISMATCH. Deferred forms such as CONTENT.PROFESSION.HIDDEN[xx].parents, unresolved, placeholder, pending, or unknown fail HIDDEN_PROFESSION_ART_BINDING_UNRESOLVED and are not also reported as a parent mismatch for the same row.

8.8 Region Content/Art Binding

REGION_CATALOG.md owns the eight RG-01..08 names, minimal framing, encounter behavior/grammar, and production needs. The Eight Region Keys table in ART_ASSET_AND_ANIMATION_CATALOG.md must provide exactly one row for every ART-REG-01..08 and a dedicated exact-content-binding cell. Each art ID binds the same-ordinal region ID, and every region ID has exactly one art owner; a permutation, omission, repeated target, or multiple targets in one cell fails.

The validator derives comparison anchors from the current content matrix rather than keeping a second hard-coded region map. It requires the exact content name in the biome/landmark brief, then compares region-distinctive normalized terms for three channels: biome/landmark framing, palette/light/material production needs, and hazard/mechanic behavior plus encounter grammar. A channel must meet its minimum content-anchor count and cannot match another region at least as strongly as its bound region. This permits independently authored production language while rejecting an ordinal brief copied from an unrelated biome. Missing, non-bijective, wrong-ordinal, unnamed, weak, or conflicting rows fail REGION_ART_BINDING_MISMATCH.

9. Diagnostics And Exit Contract

Run from the repository root:

python3 tools/validate_predevelopment_design.py
python3 tools/validate_predevelopment_design.py --json
python3 tools/validate_predevelopment_design.py --self-test

Diagnostics sort by path, line, column, code, and message. Text output ends in one of:

ABG_PREDEVELOPMENT_DESIGN_OK errors=0
ABG_PREDEVELOPMENT_DESIGN_FAILED errors=<n>

Exit status is 0 only when no diagnostic remains and 1 for an audit failure. The executable imports no third-party package.

The main diagnostic families are:

Family	Meaning
AUTHORITY_*	required authority missing or unreadable
REGISTRY_*, ENEMY_*	exact-set, count, gap, class, or row failure
ID_DUPLICATE	a canonical definition is repeated
REFERENCE_*	a stable reference or range is malformed/unresolved
BINDING_*	declaration missing/duplicated or value unresolved
RETIRED_*	obsolete product authority remains positive
PAGE_*, ART_*, AUDIO_*	presentation registry or coverage absent
PROVISIONAL_SELECTION_*	product selected/offered values are missing, inconsistent, or absent from row-bound presentation
PARTY_DIRECTION_MISMATCH	UI and art disagree on left/right exposed/protected endpoints
RECRUIT_ART_CROSSWALK_MISMATCH	recruit fields, counts, sources, or deterministic mappings do not agree
AUDIO_SCREEN_INVENTORY_MISMATCH	audio screen IDs/count do not equal the primary screen registry
REFERENCE_RETIRED_SCOPE	the scoped reference authority positively prescribes retired cast/relationship scope
RUN_CREATION_SEED_ORDER_MISMATCH	durable seed/read-back does not precede and authorize opening generation
RUN_CREATION_TRANSACTION_INCOMPLETE	exact-four materialization, revisable pair, atomic promotion, or exactly-once retry evidence is incomplete
HIDDEN_PROFESSION_ART_MISMATCH	hidden art identity, parents, mechanic, silhouette/props, VFX, or actions disagree with content
HIDDEN_PROFESSION_ART_BINDING_UNRESOLVED	hidden art delegates a required row binding to unresolved/pending language
REGION_ART_BINDING_MISMATCH	region art mapping is missing, non-bijective, wrong-ordinal, unnamed, or semantically conflicts with content

10. Self-test And Integrated Evidence

The generated pass fixture uses the integrated schemas and includes regression coverage for every false-positive class from Attempt 1:

• PF-*, regional EN-R*, BO-R*, and RG-* primary registries
• topology and count cross-reference tables that repeat IDs
• explicit retired-concept negation and a negative search command
• non-spatial three-band cadence language
• abbreviated, suffix, brace, and mixed-prefix ranges
• music/ambience tables plus fenced voice/SFX registries
• underscore-based inspection events
• a coherent two-of-four provisional flow in both stable-screen and onboarding rows
• matching UI/art party endpoints
• all ten generated-recruit crosswalk rows with compatible source counts
• an exact screen/audio ID set including OUT-006
• historical/rejection-only reference mentions of retired scope
• a durable seed-only draft read back before opening generation, followed by exact-four materialization, revisable exact-pair selection, and atomic exactly-once Run promotion
• six content-owned hidden-profession parent/mechanic/production briefs with exact resolved silhouette, prop, VFX, and action bindings
• eight same-ordinal region-art bindings with exact names and content-derived biome/landmark, palette/material, and hazard/mechanic anchors
• an alternate integrated-shape pass using staged SYS-005 onboarding, side-first endpoint clauses, embedded stored-authority counts, and bounded art-binding ranges

Negative fixtures cover exact counts, regional gaps, primary duplicates, broken references, unresolved and unknown bindings, unbounded ranges, positive retired concepts, filler rows, page/art/audio omissions, audio duplicates, and one isolated mutation for each of the five Experience R3 contradiction classes. Four additional isolated R4 mutations invert seed/generation order, remove the atomic promotion proof, substitute a mechanic-incompatible hidden-art package, and restore a deferred hidden-parent pointer. Four isolated R6 mutations remove one mapping, swap two wrong region IDs, duplicate one region target, and replace one biome brief with another region's landmarks. The five R3 mutations run after rewriting the fixture into the alternate integrated shape, while the R4 and R6 mutations run against the same positive semantic fixture. Flexible positive parsing therefore cannot weaken any negative boundary. The success terminal is:

ABG_PREDEVELOPMENT_DESIGN_SELF_TEST_OK cases=28

On integrated product revision 8102bd2, all prior exact content/audio registry checks remain satisfied and the repaired real documents resolve with zero diagnostics. The self-test still proves all five immutable Experience R3 contradiction classes fail independently, and now also proves both R4 failure boundaries in two ways each: seed order versus durable transaction completeness, and hidden mechanic mismatch versus unresolved art binding. R6 independently proves missing, wrong-ordinal, duplicate-target, and conflicting-brief region art failures.