================================================================================
COLLABTUNES GENERATOR INPUT REQUIREMENTS
Version: 1.0 | Date: 5_13_26 | Status: AUTHORITATIVE
Owner: Mixed Claude / Tom
Purpose: Definitive spec for what the AIO page generator requires as input.
         Any input not meeting these specs will cause generator failure or
         incorrect output. Verify all inputs before generator run.
================================================================================

================================================================================
SECTION 1 — REQUIRED INPUT FILES
================================================================================

The following 5 files are REQUIRED for generator operation.
All must be at AUTHORITATIVE or LOCKED status before generator runs.
If any file is MISSING or WORKING status: generator must not run.

--------------------------------------------------------------------------------
INPUT 1: MOOD SETTINGS (CRITICAL — highest priority)
--------------------------------------------------------------------------------
Required filename pattern:  mood_settings_ratings_explicit_for_all_34_albums
File type:                  TXT
Authority required:         AUTHORITATIVE or LOCKED
Location:                   03_RATINGS/ or 02_CANON/
Expected folder:            03_RATINGS/

Content requirements:
  - Must cover all 34 collections (24 Set Lists + 10 Song Lists)
  - Each collection entry must include:
    * Collection ID (e.g. SET_LIST_1, SONG_LIST_1)
    * Collection title (exact canonical form)
    * Content rating (G | PG | PG-13 | R | NC-17 | X)
    * Gate requirement (NONE | PG13_REQUIRED | R_REQUIRED | NC17_REQUIRED | X_REQUIRED)
    * Mood tag(s) (at least one per collection)
  - No collection may have rating=PENDING or rating=CONFLICT
  - No collection may have gate=UNKNOWN
  - Date stamp must be present

Validation check before generator run:
  [ ] File exists at AUTHORITATIVE or LOCKED status
  [ ] All 34 collections present (count = 34)
  [ ] Zero PENDING ratings
  [ ] Zero CONFLICT ratings
  [ ] Zero UNKNOWN gate requirements

--------------------------------------------------------------------------------
INPUT 2: MASTER CONTENT RATINGS INDEX
--------------------------------------------------------------------------------
Required filename pattern:  MASTER_CONTENT_RATINGS_INDEX_VOL{N}_{DATE}.txt
File type:                  TXT
Authority required:         AUTHORITATIVE
Location:                   03_RATINGS/
VOL requirement:            Must be highest available VOL number

Content requirements:
  - All 34 collections have at least one entry
  - All 434 titles have rating entries (or explicitly marked PENDING)
  - Rating format: {TITLE} | {RATING} | {AUTHORITY_STATUS}
  - No duplicate title entries with conflicting ratings
  - Date stamp matches or is later than mood_settings file

Validation check:
  [ ] File exists, VOL is latest
  [ ] Count of unique collection entries = 34
  [ ] No title appears twice with different ratings (AMBIGUOUS_VERSION)
  [ ] Zero CONFLICT entries (or all documented in blocker registry)

--------------------------------------------------------------------------------
INPUT 3: FINAL CANON AUTHORITY REGISTRY
--------------------------------------------------------------------------------
Required filename pattern:  FINAL_CANON_AUTHORITY_REGISTRY_{DATE}.txt
File type:                  TXT
Authority required:         LOCKED or AUTHORITATIVE
Location:                   02_CANON/

Content requirements:
  - All 34 collections registered
  - All known conflicts documented (CC-LW, CC-CH18, etc.)
  - Slug canonical form for each collection confirmed
  - No unresolved conflicts that affect AIO page generation
  - LOCKED status entries cannot be overwritten by generator

Validation check:
  [ ] File exists at LOCKED or AUTHORITATIVE
  [ ] All 34 collections present
  [ ] All known conflicts have status (not blank)
  [ ] Zero OPEN conflicts on fields generator will write

--------------------------------------------------------------------------------
INPUT 4: MASTER URL AUTHORITY REGISTRY
--------------------------------------------------------------------------------
Required filename pattern:  MASTER_URL_AUTHORITY_REGISTRY_VOL{N}_{DATE}.txt
File type:                  TXT
Authority required:         AUTHORITATIVE
Location:                   05_URL_MAPS/

Content requirements:
  - All live pages registered with correct status (LIVE | BROKEN | PENDING)
  - All AIO pages have confirmed slug
  - No duplicate slugs for same page
  - All known URL conflicts documented (BLOCK-H04, BLOCK-M01, etc.)
  - Date stamp current

Validation check:
  [ ] File exists, VOL is latest
  [ ] All AIO page slugs confirmed LIVE
  [ ] Zero undocumented duplicate slugs
  [ ] Lady Weaver conflict status documented (BLOCK-H04)

--------------------------------------------------------------------------------
INPUT 5: HTML TESTER (Color-Corrected Reference)
--------------------------------------------------------------------------------
Required filename pattern:  HTML_TESTER_NUMBER_TWO_FIXED_COLOR_{DATE}.html
File type:                  HTML
Authority required:         AUTHORITATIVE
Location:                   09_HTML_PROTOTYPES/

Content requirements:
  - This is the visual reference template for AIO page generation
  - Color palette must be the approved, corrected version
  - All section anchors must be present and unique
  - Fast scroll system must be present and functional
  - Rating badge placement confirmed
  - Gate integration points marked

Validation check:
  [ ] File exists with FIXED_COLOR in name
  [ ] File is the correct (non-broken-color) version
  [ ] All anchors validated
  [ ] Renders correctly in browser before generator run

================================================================================
SECTION 2 — ANCHOR NAMING STANDARD
================================================================================

PURPOSE: Anchor IDs must be stable. The generator hard-codes these IDs.
Any anchor change after generator runs = broken internal links everywhere.

ANCHOR ID FORMAT:
  {SCOPE}_{IDENTIFIER}_{DESCRIPTOR}
  All lowercase. Hyphens only (no underscores in actual HTML id= attributes).
  Max 60 characters.

SCOPE VALUES:
  top         — page-level top anchor (every page must have this)
  mid         — page-level mid anchor
  bot         — page-level bottom anchor
  nav         — navigation element
  sec         — content section
  sl          — song list reference
  set         — set list reference
  ch          — chapter reference
  gate        — content gate element

EXAMPLES (correct):
  id="top"
  id="mid"
  id="bot"
  id="nav-128-section-01"
  id="sec-mood-settings"
  id="sl-01-the-last-man-singing"
  id="set-03-self-in-the-mirror"
  id="ch-07-quick-guide-g-to-x"
  id="gate-r-required"

EXAMPLES (wrong — do not use):
  id="TOP"                    ← uppercase
  id="nav_128_01"             ← underscores in HTML id
  id="section1"               ← not descriptive enough
  id="temp-anchor-2"          ← "temp" is a banned word
  id="new-section"            ← "new" is a banned word

ANCHOR STABILITY RULE:
  Once an anchor is in a deployed page, it cannot be renamed without:
  1. A blocker entry documenting the change
  2. All internal links to that anchor updated simultaneously
  3. A new VOL of the URL registry reflecting the change

REQUIRED ANCHORS (every page must have these three):
  id="top"    — absolute top of page
  id="mid"    — midpoint of page (for long pages)
  id="bot"    — absolute bottom of page

================================================================================
SECTION 3 — METADATA BLOCK FORMAT
================================================================================

Every AIO page generator output must include a metadata block.
This block is machine-readable and human-readable.
Place at the top of each generated file as an HTML comment block.

FORMAT:
<!-- COLLABTUNES PAGE METADATA
  PAGE_TYPE:       {ALBUM_AIO | NAV | SONGBOOK | QUICKGUIDE | HGIH | PLACEHOLDER}
  COLLECTION_ID:   {SET_LIST_{N} | SONG_LIST_{N}}
  COLLECTION_TITLE:{Exact canonical title}
  SLUG:            {/slug/}
  CONTENT_RATING:  {G | PG | PG-13 | R | NC-17 | X}
  GATE_REQUIRED:   {NONE | PG13_REQUIRED | R_REQUIRED | NC17_REQUIRED | X_REQUIRED}
  SAFE_ROUTE:      {OPEN | GATED_PG13 | GATED_R | GATED_NC17 | GATED_X}
  AUTHORITY:       {LOCKED | AUTHORITATIVE | WORKING}
  GENERATED_BY:    {generator_run_id}
  GENERATED_DATE:  {M_D_YY}
  SOURCE_FILES:    {comma-separated list of input files used}
  VERSION:         {VOL number}
  SUPERSEDES:      {prior page version filename, or NONE}
-->

RULES:
  - No field may be null or empty
  - CONTENT_RATING must match MASTER_CONTENT_RATINGS_INDEX
  - GATE_REQUIRED must match RATING_TO_GATE mapping
  - SLUG must match MASTER_URL_AUTHORITY_REGISTRY
  - AUTHORITY starts as WORKING, becomes AUTHORITATIVE after Tom review

================================================================================
SECTION 4 — JSON READINESS REQUIREMENTS
================================================================================

For any JSON file to be accepted as generator input:

STRUCTURAL REQUIREMENTS:
  - Valid JSON (parseable without errors)
  - Top-level object (not array) as root
  - run_id field present (string)
  - run_mode field present ("DRY_RUN" or "LIVE_RUN")
  - source_code_version field present
  - items[] or files[] array present
  - Every item in array has all required fields (no missing keys)

FIELD REQUIREMENTS FOR ITEMS USED IN GENERATION:
  url:            non-null string, starts with https://
  slug:           non-null string, starts and ends with /
  label:          non-null string, not "Unknown"
  http_status:    200 (non-200 items must not be passed to generator)
  page_type:      one of PAGE_TYPES list (not UNKNOWN)
  rating:         not PENDING, not UNKNOWN, not CONFLICT
  gate_requirement: not UNKNOWN
  safe_route:     not UNKNOWN
  authority:      not UNKNOWN

PRE-GENERATOR JSON VALIDATION CHECKLIST:
  [ ] JSON parses without errors
  [ ] Zero items with http_status ≠ 200 in generation input
  [ ] Zero items with rating=PENDING in generation input
  [ ] Zero items with page_type=UNKNOWN in generation input
  [ ] Zero items with gate_requirement=UNKNOWN on R+ rated pages
  [ ] All slugs match entries in MASTER_URL_AUTHORITY_REGISTRY

================================================================================
SECTION 5 — TXT NORMALIZATION REQUIREMENTS
================================================================================

All TXT files used as generator inputs must follow this format:

HEADER BLOCK (required at top of every TXT file):
  Line 1:  ====...==== (80 = signs)
  Line 2:  {DOCUMENT_TITLE_IN_UPPERCASE}
  Line 3:  STATUS: {AUTHORITATIVE | LOCKED | WORKING | REFERENCE | DEPRECATED}
  Line 4:  Generated: {M_D_YY} or Date: {M_D_YY}
  Line 5:  PURPOSE: {one-line description of what this file is}
  Line 6:  SUPERSEDES: {prior filename or N/A}
  Line 7:  ====...==== (80 = signs)

SECTION SEPARATORS:
  Use: ----...---- (80 dashes) between major sections
  Use: SECTION: {SECTION_NAME} as section label

DATA ENTRY FORMAT (for machine-readable TXT):
  Use pipe delimiter: {field_1} | {field_2} | {field_3}
  Consistent column order within each file
  No trailing whitespace
  UTF-8 encoding

BANNED CONTENT IN GENERATOR INPUT TXT:
  - Freeform prose paragraphs (use structured entries only)
  - Inconsistent delimiters (mixing | and , and : in same file)
  - Fields without labels (bare data with no key)
  - Duplicate entries without explicit version annotation

================================================================================
SECTION 6 — DEPLOYMENT-SAFE NAMING CONVENTIONS
================================================================================

APPLIES TO: All files that will be used by the generator, deployed to the site,
            or included in deployment packages.

FILENAME RULES:
1. All uppercase (exception: SGC module files use lowercase snake_case)
2. Words separated by underscores
3. Must include date in M_D_YY format
4. Must include VOL number if this is a versioned document
5. Must include category token from APPROVED_CATEGORIES
6. Must not include banned words: final, output, new, fixed, temp, test,
   untitled, copy, export, revised

COLLECTION TITLE CANONICAL FORMS:
Use exactly these forms in all filenames, metadata, and registries:

Set Lists:
  SET_LIST_1  through  SET_LIST_24
  (Use underscore, not hyphen, in filenames)

Song Lists:
  SONG_LIST_1  through  SONG_LIST_10
  (Use underscore, not hyphen, in filenames)

Chapter references in filenames:
  CH_{N}_OF_35_{TITLE}   (e.g. CH_7_OF_35_QUICK_GUIDE_G_TO_X)

In HTML slug form (different from filename form):
  /set-list-{n}/          (lowercase, hyphens)
  /song-list-{n}/         (lowercase, hyphens)
  /{n}-of-35-{title}/     (lowercase, hyphens)

These two forms are distinct — do not mix them.
Filename uses underscores. Slug uses hyphens. Never cross-contaminate.

================================================================================
SECTION 7 — GENERATOR RUN PROTOCOL
================================================================================

PRE-RUN GATES (all must be TRUE before generator runs):
  [ ] All 5 required inputs are at AUTHORITATIVE or LOCKED
  [ ] Deployment readiness audit Section 9 (gate integrity) = PASS
  [ ] Zero CRITICAL blockers in blocker registry
  [ ] Output directory is 14_GENERATED_OUTPUT/ (never 02_CANON/ or 05_URL_MAPS/)
  [ ] Generator has DRY_RUN mode and it has been tested first
  [ ] Rollback ZIP of current stable state exists

GENERATOR RUN ORDER:
  1. DRY_RUN first — review output list before any files are written
  2. Review dry run report — check file count, naming, no errors
  3. LIVE_RUN — generates actual files
  4. Review generated files — spot-check at least 5 outputs
  5. Run deployment audit on generated files
  6. Tom reviews and approves
  7. Move from 14_GENERATED_OUTPUT/ to deployment package

POST-RUN:
  [ ] Generated files have metadata blocks
  [ ] All generated anchors match anchor naming standard
  [ ] No generated file has rating=UNKNOWN
  [ ] No generated R+ page is missing a gate
  [ ] Generator run_id logged in manifest

================================================================================
END COLLABTUNES GENERATOR INPUT REQUIREMENTS
================================================================================
