📖 Stories Maker V4 — Kitchen Pipeline

Multi-genre content engine with deterministic quality gates — 11 phases, 17 gates, 7 genres, 71 tests

System Overview

╔══════════════════════════════════════════════════════════════════════╗ ║ AVA v2 STORY ORCHESTRATOR ║ ║ ║ ║ source_data ───▶ ORCHESTRATOR FSM (main.py) ║ ║ ║ ║ Phase 0 ──G0──▶ Phase 1 ──G1──▶ Phase 2 ──G2──▶ Phase 3 ║ ║ [IDEATION] [RESEARCH] [BIBLE_DRAFT] [BIBLE_LOCK] 🔒 ║ ║ G3 (HUMAN ✋) ║ ║ │ ║ ║ Phase 4 ◀───────────────────────────────────────────┘ ║ ║ [OUTLINE] G3.5 + G4A/B/C ║ ║ │ ║ ║ Phase 5 [SCENE_LOOP] ← Core production loop ║ ║ ┌─────────────────────────────┐ ║ ║ │ for each scene_spec: │ ║ ║ │ Writer → 6 Auditors │ ║ ║ │ → Gate5 Tier1+Tier2 │ ║ ║ │ → G5 token or REWRITE │ ║ ║ └─────────────────────────────┘ ║ ║ │ ║ ║ Phase 6 [ASSEMBLY] G6 + G7 ║ ║ Phase 7 [OUTPUT] G8 (HUMAN ✋) ║ ║ Phase 8 [THUMB/SEO] G8.5 ║ ║ Phase 9 [UPLOAD] G9 + G9.5 ║ ║ Phase 10 [MONITOR] G10 ║ ╚══════════════════════════════════════════════════════════════════════╝

Design Pillars

Determinism	SHA-256 gate tokens — identical inputs = identical decisions
Sequential	`_PHASE_ORDER` list — no skipping allowed
Separation	Auditors evaluate → Arbiter decides → Gates enforce → Writer creates
Immutability	Bible locked after G3 — tokens append-only JSONL
Fail-safe	Policy violation → immediate ABORT
Cost-conscious	Hard cost limits per mode — escalations abort, not loop

⚙️ 11 Pipeline Phases (0-10)

0

Phase 0 — IDEATION
Writes policy_bundle.md to disk. Gate G0 validates policy loaded.
Auto G0
1

Phase 1 — RESEARCH
Source quality check. source_analysis.quality_score ≥ 0.7
Auto G1
2

Phase 2 — BIBLE DRAFT
Originality screen. outline_data.originality_score ≥ 0.85. Character bible + V4 expanded character sheet (archetype, villain layers, visual cards).
Auto G2
3

Phase 3 — BIBLE LOCK 🔒
Bible schema validation → PENDING_HUMAN. Rio approves → bible locked (immutable, checksum-protected). Cannot be modified after G3.
✋ Human Gate G3
4

Phase 4 — OUTLINE
Scene spec validation (G3.5) + parallel audits: canon consistency (G4A), timeline causality (G4B), originality pre-screen (G4C).
Auto G3.5 G4A G4B G4C
5

Phase 5 — SCENE LOOP ⭐ Core Loop
For each scene: Writer → 6 Auditors (parallel) → Gate5 Tier1 (binary) + Tier2 (numeric). Max 3 rewrites per scene. Backstory placement per mode. Villain layer2 reveal. Thesis delivery.
Auto G5 ×N scenes
6

Phase 6 — ASSEMBLY
Cross-scene batch audit (G6). Assembly word-count + structure check (G7).
Auto G6 G7
7

Phase 7 — OUTPUT
Final QA: quality scores vs SCRIPT_STANDARDS. PENDING_HUMAN for Rio approval.
✋ Human Gate G8
8

Phase 8 — THUMBNAIL & SEO
SEO package generation: title, tags, description, thumbnail.
Auto G8.5
9

Phase 9 — UPLOAD
Output package complete (G9) + upload confirmed (G9.5).
Auto G9 G9.5
10

Phase 10 — MONITORING
Post-publish analytics started. Performance tracking begins.
Auto G10

🚦 Gate System — 17 Gates

Mỗi gate issue một GateToken (SHA-256 checksum, append-only JSONL). bypass_allowed structurally = False. Self-pass prevention: Writer không thể issue token cho chính mình.

Gate	Phase	Type	Issuer	Description
`G0`	0 — Ideation	Auto	Arbiter	Policy bundle loaded
`G1`	1 — Research	Auto	Arbiter	Source quality ≥ 0.7
`G2`	2 — Bible Draft	Auto	Arbiter	Originality score ≥ 0.85
`G3`	3 — Bible Lock	✋ Human	Human	Bible approved by Rio
`G3.5`	4 — Outline	Auto	Arbiter	Scene spec JSON schema valid
`G4A`	4 — Outline	Auto	Arbiter	Canon consistency
`G4B`	4 — Outline	Auto	Arbiter	Timeline causality
`G4C`	4 — Outline	Auto	Arbiter	Originality pre-screen
`G4`	4 — Outline	Auto	Arbiter	Combined G4A+B+C summary
`G5`	5 — Scene Loop	Auto	Arbiter	Per-scene quality (×N scenes)
`G6`	6 — Assembly	Auto	Arbiter	Cross-scene batch audit
`G7`	6 — Assembly	Auto	Arbiter	Assembly word-count + structure
`G8`	7 — Output	✋ Human	Human	Final QA approved by Rio
`G8.5`	8 — Thumb/SEO	Auto	Arbiter	SEO package generated
`G9`	9 — Upload	Auto	Arbiter	Output package complete
`G9.5`	9 — Upload	Auto	Arbiter	Upload confirmed
`G10`	10 — Monitor	Auto	Arbiter	Post-publish analytics started

Gate 5 — Two-Tier Decision System

Tier 1 — Binary Decision (6 dimensions)

Rule	Condition	Decision
1	Policy = FAIL	ABORT (no recovery)
2	All 6 = PASS	→ Advance to Tier 2
3	1-2 non-policy FAILs, attempt < max	REWRITE
4	3+ non-policy FAILs	ESCALATE
5	Any FAIL, attempt ≥ max	ESCALATE (Guided) / ABORT (Auto)

Tier 2 — Quality Score Thresholds

Dimension	Minimum
Consistency	9.0
Originality	8.5
Hook	8.5
Cliffhanger	8.0
Emotional	8.5
TTS	9.0

Any score below minimum → REWRITE (even if all Tier-1 passed). All scores ≥ minimum → PASS → G5 token issued.

🎭 Genre Registry — 7 Genres (V4)

Genre	Label	Default Archetype	Villain Layers	Backstory	Thesis
`revenge`	Family Revenge / Betrayal	betrayed_victim	1	front_loaded	narrator
`healing`	Healing / Recovery	wounded_survivor	1	front_loaded	narrator
`redemption`	Redemption / Invisible Good	invisible_giver	1	woven	environmental
`hidden_identity`	Hidden Identity / Competence Reveal	suppressed_identity	2	earned	character_spoken
`injustice`	Injustice / Wrongful Accusation	wrongly_accused	2	revelation	protagonist_earned
`transformation`	Transformation / Underdog Rise	underdog	1	woven	environmental
`default`	Default (Legacy)	betrayed_victim	1	front_loaded	narrator

Required Beats per Genre

🗡️ Revenge

betrayal → discovery → confrontation → resolution

💚 Healing

wound → breakdown → turning_point → acceptance

🕊️ Redemption

selfless_act → unrewarded_stretch → unfair_opponent_rise → opponent_fall → quiet_payoff

🎭 Hidden Identity

hidden_state → crisis_trigger → competence_reveal → backstory_earn → villain_layer2_exposed → identity_restored

⚖️ Injustice

accusation → isolation → ally_appears → evidence_found → true_villain_exposed → vindication

🦋 Transformation

low_point → catalyst → first_win → setback → mastery → proving_moment

👤 Archetype Registry — 7 Protagonist Types

Archetype	Label	Traits	Compatible Genres
`betrayed_victim`	Victim of Betrayal	Trusting → discovers betrayal → fights back	revenge, healing
`wounded_survivor`	Wounded Survivor	Deep wound → survival mode → healing journey	healing, transformation
`invisible_giver`	Invisible Giver	Gives without expectation → unrewarded → quiet payoff	redemption
`suppressed_identity`	Suppressed Identity	Hides true self → crisis forces reveal → identity restored	hidden_identity, transformation
`wrongly_accused`	Wrongly Accused	Falsely blamed → fights system → truth emerges	injustice
`underdog`	Underdog	Overlooked → catalyst event → rises through effort	transformation, redemption
`hidden_competence`	Hidden Competence	Appears ordinary → forced to act → reveals expertise	hidden_identity

📜 Backstory Delivery Modes — 4 Modes

📖 Front-loaded

Backstory told in Act 1, action follows.

Window: First 25% of story (0.0 – 0.25)

revenge healing

🏆 Earned

Protagonist acts first → audience earns backstory later.

Window: Middle 40-70% (0.4 – 0.7)
Rule: Protagonist MUST demonstrate competence BEFORE backstory revealed

hidden_identity

🧵 Woven

Backstory fragments woven throughout, building incrementally.

Window: Distributed 10-80% (0.1 – 0.8)
Fragments: 3-5 flashback moments

redemption transformation

💥 Revelation

True backstory only revealed near climax — reframes everything.

Window: Late 70-90% (0.7 – 0.9)
Rule: Early scenes MUST work WITHOUT backstory context

injustice hidden_identity

💡 Thesis Delivery Modes — 4 Modes

Mode	Description	Strength	Compatible Genres
`narrator`	Narrator directly delivers moral/theme	Clear but can feel preachy	revenge, healing
`character_spoken`	Supporting character delivers core truth	Feels earned — from within story	hidden_identity
`protagonist_earned`	Protagonist realizes truth through experience	Most powerful — earned through action	injustice, transformation
`environmental`	No one states thesis — shown through contrasting actions	Most subtle — audience concludes	redemption

🔍 Auditor System — 6 Dimensions

All 6 auditors run concurrently via asyncio.gather(). Each returns AuditResult with verdict (PASS/FAIL), error code, severity, quality scores.

Auditor	Dimension	Error Code	What It Checks
Canon	Character consistency	`CANON_CONFLICT`	Characters match bible traits, arcs, relationships
Timeline	Causality + temporal	`TIMELINE_ERROR`	Event ordering, prerequisites, temporal logic
Fact	Factual verification	`FACT_DRIFT`	Claims match fact ledger, no contradictions
Originality	Duplicate detection	`LOW_ORIGINALITY`	Content uniqueness, no plagiarism
Policy	Content compliance	`POLICY_VIOLATION`	No dark psych, no celebrity images, ethical content
Style	Voice + tone	`STYLE_DRIFT`	Narrator persona consistency, tone matching

Conflict Resolution Priority (highest → lowest)

1. FACT → 2. CANON → 3. TIMELINE → 4. ORIGINALITY → 5. STYLE → 6. POLICY (always ABORT)

When auditors disagree on same dimension: FAIL verdict wins (conservative).

✏️ Rewrite Engine

Scope Escalation Ladder

Attempt	Scope	Description	Context Loaded
1	L1/L2	Minimal fix (word/sentence)	Target sentence or paragraph
2	L3	Paragraph rewrite	Scene section + bible cast summary
3	L4	Full scene rewrite (final attempt)	Full bible, timeline, fact ledger, scene spec

Cost Containment

Max 3 attempts — hard cap per scene
Scope escalation — smaller scopes first = fewer tokens
Early exit — Policy violation = ABORT immediately (no retries)
Fail-fast — 3+ simultaneous failures = ESCALATE (don't waste tokens)

🎭 Villain Architecture — 2-Layer System

Layer 1 — Visible Antagonist

Always present. Direct opposition to protagonist.

Role: Executor
Arc: escalate → overreach → exposed
Example: "Tristan" (Hidden Identity)

Layer 2 — Hidden Architect

Optional (for hidden_identity, injustice). Creates "second twist".

Role: Architect
Arc: invisible → hints → full exposure Act 3
Reveal: Scene 60-90% of story
Example: "Ashford Sr." (Hidden Identity)

📥 Intake Schema V2 — New Fields

# input_intake.yaml — V2 Schema
genre: "hidden_identity"           # 7 options từ GENRE_REGISTRY

protagonist:
  name: "Elena Vasquez"
  archetype: "suppressed_identity" # từ ARCHETYPE_REGISTRY
  visible_persona: "Quiet cleaning lady"
  hidden_truth: "Former international translator"

villain_architecture:
  layers: 2
  layer_1: { name: "Tristan", role: "executor" }
  layer_2: { name: "Ashford", role: "architect", reveal_timing: 0.75 }

backstory_mode: "earned"           # 4 modes
thesis:
  mode: "character_spoken"         # 4 modes
  core_message: "Identity isn't what they took..."
  speaker: "Elena's mother"

unfair_opponent:                   # Optional (redemption genre)
  name: "Jerome"
  philosophy: "Take everything, give nothing"

emotional_curve_override: null     # null = use genre default

Validation Rules

Genre must be in GENRE_REGISTRY
Archetype must be compatible with genre
Villain layers must match genre default or be justified
Backstory mode must be compatible with genre
Thesis mode must be compatible with genre
If unfair_opponent → genre should be "redemption"
If villain layers == 2 → layer_2.reveal_timing must be 0.6-0.9

💾 State Management — 5 Persistent Objects

Object	File	Lifecycle	Key Feature
Bible Lock	`story_bible_lock.json`	Created Phase 3 → locked forever	SHA-256 checksum, immutable after G3
Fact Ledger	`fact_ledger.json`	Updated Phase 1-5	FACT/INFERENCE/CREATIVE/UNKNOWN labels
Timeline Grid	`timeline_grid.json`	Updated Phase 1-5	Causality validation via prerequisites
Scene Spec	`scene_specs/{id}.json`	Created Phase 4, read-only Phase 5	Goal, beats, emotional turn, hooks
Scene Log	`scene_logs/{id}.json`	Append-only Phase 5	Version history, scores, rewrite tasks

🔀 Guided vs Auto Mode

Behaviour	Guided	Auto
G3 (Bible Lock)	Pauses → PENDING_HUMAN	No pause
G8 (Final QA)	Pauses → PENDING_HUMAN	No pause
ESCALATE in scene	Pauses → PENDING_HUMAN	Returns ABORTED
Model strategy	claude-opus-4.6 (all agents)	Hybrid (haiku auditors, sonnet writer)
Cost limit (soft/hard)	$200 / $300	$100 / $150
Max rewrites	15 per scene	15 per scene

💰 Cost Optimisation Strategy

Model Selection Matrix

Agent Role	Guided Model	Auto Model
Scene Writer	claude-opus-4.6	claude-sonnet-4
Canon Auditor	claude-opus-4.6	claude-haiku-3
Timeline Auditor	claude-opus-4.6	claude-haiku-3
Fact Auditor	claude-opus-4.6	claude-sonnet-4
Originality Auditor	claude-opus-4.6	claude-haiku-3
Policy Auditor	claude-opus-4.6	claude-haiku-3
Style Auditor	claude-opus-4.6	claude-haiku-3

Budget Safeguards

Per-run cost flow:
  tokens_used (per scene version in SceneLog)
      ↓
  credits_used (accumulated)
      ↓
  soft_limit reached → WARNING, continue
      ↓
  hard_limit reached → ABORTED("Cost limit exceeded")

🧩 Component Map

orchestrator_v2/
├── main.py              # Orchestrator FSM entry point
├── config.py            # GENRE_REGISTRY, ARCHETYPE_REGISTRY, modes, thresholds
│
├── gates/               # Gate enforcement layer
│   ├── token_engine.py  # GateToken + SHA-256 checksums
│   ├── gate_5.py        # Tier-1 binary + Tier-2 numeric
│   ├── gates_0_3.py     # G0, G1, G2, G3
│   ├── gates_4.py       # G3.5, G4A, G4B, G4C
│   └── gates_6_8.py     # G6, G7, G8
│
├── arbiter/             # Decision engine
│   ├── decision_engine.py
│   └── phase2_mode.py   # AUTO escalation handler
│
├── auditors/            # 6 quality auditors
│   ├── canon_auditor.py
│   ├── timeline_auditor.py
│   ├── fact_auditor.py
│   ├── originality_auditor.py
│   ├── policy_auditor.py
│   └── style_auditor.py
│
├── agents/              # Sub-agent integration
│   ├── intake_validator.py   # V4 cross-validation
│   ├── bible_builder.py      # Expanded character sheet
│   ├── scene_builder.py      # Backstory placement, villain reveal
│   ├── scene_writer.py
│   ├── story_architect.py
│   ├── renderer.py
│   ├── thumbnail_generator.py
│   └── youtube_uploader.py
│
├── state/               # Persistent state objects
│   ├── bible_lock.py
│   ├── fact_ledger.py
│   ├── timeline_grid.py
│   ├── scene_spec.py
│   └── scene_log.py
│
├── rewrite/
│   └── rewrite_engine.py
│
├── context/
│   └── context_manager.py
│
├── dashboard/           # Dashboard connector
│   └── dashboard_connector.py
│
└── tests/               # 71 passing tests

AVA Stories Maker V4 — Kitchen Pipeline Documentation
Last updated: 2026-03-24 | Branch: dev | Commit: cc91ff2