| name | content-authority-integration |
| description | Use when integrating YAML content authority (God of Carnage builtin roles) into turn execution, testing authority conflict detection, verifying YAML module loads correctly, or ensuring content authority flows through turn graph |
Content Authority Integration
Overview
Systematically integrate YAML content authority (God of Carnage builtin roles, relationships, attributes) into turn execution. Ensures YAML authority is consulted at all decision points, conflicts detected correctly, and YAML definitions override builtins as intended.
When to Use
Trigger when:
- Integrating YAML authority module into turn graph
- Testing builtin vs YAML conflict detection
- Verifying YAML module loads and caches correctly
- Checking turn validation uses YAML authority
- Testing commit effects respect content authority
- Ensuring visibility renders content authority correctly
When NOT to use:
- Creating new YAML authority definitions (requires content design)
- Debugging single rule failure (test in isolation first)
- Modifying YAML schema (requires architecture review)
Structured Approach
Phase 1: Authority Mapping
Identify all YAML authority points in system:
YAML AUTHORITY SOURCES:
1. builtin/roles.yaml
- Defines: God of Carnage roles (deity, shaman, warrior, etc.)
- Authority over: Character type, abilities, restrictions
2. builtin/relationships.yaml
- Defines: Allowed relationships (god-mortal, enemy, ally, etc.)
- Authority over: Relationship creation, modification
3. builtin/attributes.yaml
- Defines: Character attributes (strength, wisdom, charisma, etc.)
- Authority over: Attribute validation, ranges, mutations
4. builtin/vocabulary.yaml
- Defines: Dramatic vocabulary set (allowed action words)
- Authority over: Action proposal validation
5. builtin/scenes.yaml
- Defines: Scene templates and rules
- Authority over: Scene transitions, nesting
For each authority source, map to turn graph integration points:
INTEGRATION POINT 1: Proposal Generation
- Action: User proposes action with character
- Authority check: Is character_role in allowed roles? (check builtin/roles.yaml)
- Use YAML? YES - validate proposed action against role restrictions
INTEGRATION POINT 2: Validation
- Action: Validate proposed action
- Authority check: Does action respect relationships? (check builtin/relationships.yaml)
- Use YAML? YES - reject if action violates relationship authority
INTEGRATION POINT 3: Commit Effects
- Action: Apply state changes from validated turn
- Authority check: Are attribute changes within allowed ranges? (check builtin/attributes.yaml)
- Use YAML? YES - clamp/reject if changes exceed authority limits
INTEGRATION POINT 4: Visibility Rendering
- Action: Render turn result to players
- Authority check: Is vocabulary in approved set? (check builtin/vocabulary.yaml)
- Use YAML? YES - sanitize or reject rendering if vocabulary not approved
Phase 2: Integration Checklist
For each integration point:
| Point | Question | Check |
|---|
| Proposal Gen | Does code load YAML authority? | Verify builtin/roles.yaml loaded in proposal_generator |
| Is character role validated? | Check proposal rejects invalid roles |
| Does code handle YAML missing? | Test fallback if YAML file missing |
| Validation | Does validation consult relationships? | Check builtin/relationships.yaml consulted |
| Does validation detect conflicts? | Test conflict when action violates relationship |
| Are errors clear? | Verify error messages cite authority conflict |
| Commit | Does commit check attributes? | Check builtin/attributes.yaml consulted |
| Are mutations constrained? | Test attribute change clamped to authority limits |
| Is atomicity preserved? | Verify all attributes updated together |
| Visibility | Does rendering use vocabulary? | Check builtin/vocabulary.yaml consulted |
| Are non-approved words filtered? | Test vocabulary validation in render |
| Is output readable? | Verify filtered output is sensible |
Phase 3: Conflict Detection Design
Design logic for "YAML vs builtin" conflicts:
CONFLICT SCENARIO 1: Character Role in Builtin But Not in YAML
Builtin says: "warrior" is valid role
YAML says: "warrior" not defined (doesn't exist)
Resolution: YAML wins (newer definition beats builtin)
Action: Reject character creation with "warrior" role
CONFLICT SCENARIO 2: Relationship in YAML Contradicts Builtin
Builtin says: gods can marry mortals
YAML says: gods cannot marry mortals
Resolution: YAML wins (overrides builtin)
Action: Reject god-mortal marriage proposal
CONFLICT SCENARIO 3: Attribute Range Conflict
Builtin says: strength ranges 1-10
YAML says: strength ranges 1-20 (extended)
Resolution: YAML wins (newer limits apply)
Action: Allow strength values up to 20 per YAML
CONFLICT PRECEDENCE (from highest to lowest):
1. YAML authority (explicitly defined in YAML)
2. Builtin authority (default if YAML not present)
3. Code defaults (fallback if both missing)
Phase 4: Test Scenarios
Generate test scenarios for authority integration:
SCENARIO 1: YAML Role Override
Setup: Create character with role "warrior" in YAML
Test: Proposal generator loads YAML, accepts "warrior"
Expected: Proposal valid with "warrior" role
Assertion: YAML authority applied
SCENARIO 2: YAML Relationship Conflict
Setup: YAML forbids god-mortal marriage
Test: Proposal attempts to create god-mortal relationship
Expected: Validation fails with conflict error
Assertion: YAML authority prevented invalid relationship
SCENARIO 3: YAML Attribute Range
Setup: YAML extends strength range to 1-20
Test: Commit tries to set strength=25 (exceeds YAML limit)
Expected: Commit rejects or clamps to 20
Assertion: YAML attribute limits enforced
SCENARIO 4: Missing YAML Fallback
Setup: YAML file missing or empty
Test: Proposal uses builtin authority
Expected: Builtin defaults apply
Assertion: Graceful fallback if YAML missing
SCENARIO 5: Vocabulary Authority
Setup: YAML restricts vocabulary to approved set
Test: Action uses non-approved word
Expected: Visibility filters or rejects word
Assertion: Vocabulary authority enforced
Phase 5: Implementation Plan
Document code changes needed:
FILE: backend/world_engine/authority_loader.py (NEW)
- Purpose: Load YAML authority files on startup
- Functions:
- load_authority(authority_type) → dict
- cache_authority(data) → None
- get_authority(authority_type) → cached dict
- Error handling: Log if files missing, return empty dict
FILE: backend/world_engine/turn_graph.py (MODIFY)
- Function: generate_proposal()
- Add: authority = load_authority('roles')
- Add: validate(character.role in authority['roles'])
- Function: validate()
- Add: relationship_authority = load_authority('relationships')
- Add: validate(relationship in relationship_authority)
- Function: commit()
- Add: attribute_authority = load_authority('attributes')
- Add: clamp_attributes(attributes, attribute_authority)
- Function: render_visible()
- Add: vocabulary_authority = load_authority('vocabulary')
- Add: filter_vocabulary(output, vocabulary_authority)
FILE: backend/tests/test_authority_integration.py (NEW)
- Test 5 scenarios above
- Assert authority loaded correctly
- Assert conflicts detected
- Assert fallback works
Required Inputs
- YAML authority files (builtin/roles.yaml, relationships.yaml, etc.)
- Turn graph implementation (turn_graph.py)
- Current proposal/validation/commit logic
- Authority loader infrastructure (if exists)
- Test fixtures and harness
Outputs
Three deliverables:
-
Authority Integration Map (Markdown):
- Authority sources and definitions
- Integration points in turn graph
- Conflict resolution policy
-
Conflict Detection Policy (Markdown):
- What constitutes a conflict
- Precedence rules (YAML > builtin > defaults)
- Resolution logic
-
Test Scenarios & Implementation Plan (Markdown + Python):
- 5+ test scenarios covering integration
- Code locations needing changes
- Scaffolding for new files
Example Usage
Scenario: Integrating YAML role authority into turn graph
You:
- Map authority: Identify that proposal generation must check YAML roles
- Design conflicts: Decide YAML role definitions override builtins
- Test scenarios: Generate case where YAML role works, builtin doesn't
- Implementation: Map turn_graph.generate_proposal() to load_authority('roles')
- Deliver: Map + conflict policy + scenarios + code changes needed
Related Project Docs
- builtin/roles.yaml, relationships.yaml, attributes.yaml (authority sources)
- CANONICAL_TURN_CONTRACT_GOC.md (turn model)
- backend/world_engine/turn_graph.py (integration points)
- backend/tests/ (test patterns)
Common Mistakes
| Mistake | Fix |
|---|
| Forgot to map all integration points | Create checklist: proposal, validation, commit, visibility |
| YAML authority not consulted (code ignores YAML) | Verify code calls load_authority() at each point |
| Conflict resolution unclear (YAML vs builtin ambiguous) | Document precedence rule explicitly |
| Missing YAML fallback (crashes if file missing) | Always provide builtin defaults as fallback |
| Tests only happy path (don't test conflicts) | Include scenarios where YAML overrides builtin |
Real-World Impact
Enables God of Carnage content authority to flow through entire turn system. Prevents orphaned YAML definitions (defined but never checked). Makes authority decisions explicit and testable.
