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:

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

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

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