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:

```text
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:

```sh
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:

```text
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:

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