aetherbound-guild/docs/reviews/DESIGN_VALIDATION_CONTRACT.md

Pre-development Design Validation Contract

Contract revision: abg-design-validation-v2-crossdoc-r3-h1 Frozen input: .agent-taskgraph/spec.md revision design-spec-r3 Integrated schema evidence: b65646c 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 ten 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?

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.

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

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
• 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. Those five mutations run after rewriting the fixture into the alternate integrated shape, so flexible positive parsing does not weaken the negative gates. The success terminal remains:

ABG_PREDEVELOPMENT_DESIGN_SELF_TEST_OK cases=20

On integrated revision b65646c, all prior exact content/audio registry checks remain satisfied and the repaired real documents resolve with zero diagnostics under the H1 semantic parsers. The self-test still proves all five immutable Experience R3 contradiction classes fail when independently mutated: provisional presentation, party direction, recruit field crosswalk, OUT-006/screen total, and positive retired reference scope.