aetherbound-guild/docs/reviews/DESIGN_VALIDATION_CONTRACT.md

Pre-development Design Validation Contract

Contract revision: abg-design-validation-v2 Frozen input: .agent-taskgraph/spec.md revision design-spec-r3 Integrated schema evidence: b2d8f7b Executable: tools/validate_predevelopment_design.py Scope: merged Markdown design authorities only; 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 five 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?

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/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 product-authority scan.

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. 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

9. 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

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, and audio duplicates. The success terminal is:

ABG_PREDEVELOPMENT_DESIGN_SELF_TEST_OK cases=15

On integrated revision b2d8f7b, all content and production registry counts resolve exactly. The remaining failures are the bracket bindings declared by AUDIO_MUSIC_AND_VOICE_CATALOG.md as required integration inputs. That is an authority boundary, not a validator schema alias; the validator must continue to return nonzero until those bindings are resolved or redesigned by their owner.