title: PRD Atomic Story = 1 File, 1 Class/Function, 1 Concern

axiom: Every atomic story in a Genesis PRD MUST target exactly ONE file, ONE primary class or function, and ONE testable concern. If a story touches 2+ files as primary deliverables, it must be split.

correct: Story 2.03 — JITHydrationInterceptor | File: core/interceptors/jit_hydration.py | Class: JITHydrationInterceptor | Acceptance: pre_execute() injects ZERO_AMNESIA_STATE XML within 45ms | BB tests: 3 | WB tests: 2

incorrect: Story 3 — Build the JIT hydration system that connects to Redis and Qdrant and wraps the interceptor chain and injects context | [no file specified] [no test cases] [no budget]

rule: 1 story = 1 file = 1 class/function = 1 acceptance criterion = 1 test plan. Non-negotiable.


title: PRD Story Must Contain An Explicit Code Skeleton

axiom: Every atomic PRD story MUST include a code skeleton — at minimum the class/function signatures with type annotations. No story is complete without this. Architecture described only in words causes divergent implementations across agents.

correct:
Skeleton included:
```python
class JITHydrationInterceptor(BaseInterceptor):
    metadata = InterceptorMetadata(name='jit_hydration', priority=10)
    async def pre_execute(self, task_payload: dict) -> dict: ...
    async def post_execute(self, result: dict, task_payload: dict) -> None: ...
```

incorrect: The JIT Hydration Interceptor should retrieve context from Redis, Qdrant, and the KG, then inject it into the task payload before execution.

rule: No skeleton = no story. An agent reading a story must know exactly what to name the class, what methods it needs, and what the type signatures are.


title: PRD Story Must Name The Exact Target File Path

axiom: Every atomic PRD story MUST specify the exact file path where code is to be written. Agents MUST NOT decide file locations themselves — that leads to fragmentation and broken imports.

incorrect: Create a new file for the JIT hydration interceptor in the core directory.

rule: File path is part of the story contract. If the file doesn't exist yet, the story defines it. If it does, the story confirms it. No ambiguity.


title: PRD Story Must Have Pre-Defined Black Box And White Box Tests

axiom: Every atomic PRD story MUST define its test plan BEFORE implementation begins — minimum 3 black box + 2 white box tests named explicitly. Tests are not an afterthought. They are part of the story spec.

correct: BB tests: (1) pre_execute() injects <ZERO_AMNESIA_STATE> block into payload (2) hydration completes in < 45ms with mocked backends (3) missing task_id raises ValueError | WB tests: (1) concurrent scatter-gather fires L1+L2+L3 simultaneously (2) fallback to empty state when Redis miss

incorrect: Tests: verify the hydration works correctly.

rule: Test names are written in the PRD. Agents don't invent tests — they execute the pre-defined test plan. Zero ambiguity on what 'done' means.


title: PRD Story Must Have An Explicit Iteration Budget

axiom: Every atomic PRD story MUST include an iteration budget in the format: N implement + N run + N fix + N re-run + N stamp = total. This tells the agent when to stop, when to escalate, and prevents infinite refinement loops.

correct: Budget: 5 implement + 1 run + 2 fix + 1 re-run + 1 stamp = 10 iterations

incorrect: Implement the JIT hydration interceptor until it passes all tests.

rule: Budget is a contract. If an agent exceeds budget, it escalates rather than continuing to spin. This prevents context window burn on single stories.


title: PRD Modules Must Be Sized For Single Context Window Execution

axiom: A PRD module MUST contain no more than 10 atomic stories. Modules with 20+ stories cannot be executed in a single context window, cannot be reviewed as a unit, and cannot be assigned to a single agent. Size for assignability.

correct: Module 1: 7 stories | Module 2: 8 stories | Module 3: 7 stories | Module 4: 7 stories — each fits in one context window, assigns to one agent.

incorrect: Module 1: Memory System (25 stories covering Redis, Qdrant, KG, Cold Ledger, JIT, MVFL, routing, merging...)

rule: Max 10 stories per module. If a concern needs 15+ stories, split into two modules. Module size = agent assignment granularity.


title: PRD Must Map All Q-to-Module Before Writing

axiom: Before writing a single story, a Genesis PRD author MUST map every source question/requirement/Deep Think answer to its module(s). This prevents orphaned requirements — architecture that was discussed but never assigned to a story.

correct: Q1→Module 1+2, Q2→Module 3, Q3→Module 4, Q4→Module 1, Q5→Module 2, Q6→Module 5+6+7, Q7→Module 8+9 — confirmed all 7 DT answers have implementation homes before writing.

incorrect: Write stories for all the things we need and hope the architecture questions are covered somewhere.

rule: Q-to-module mapping is a required PRD artifact. Run it before story 1. Verify after final story. Every source requirement must map to at least one story.


title: PRD Must Include Integration Test Stories Capping Each Module

axiom: The final story of every PRD module MUST be an integration test that exercises all stories in the module together. Unit tests alone are insufficient — they don't catch interface mismatches between stories within a module.

correct: Story 1.07: Integration Test — InterceptorChain Full Pass | Verifies all 6 prior stories work together end-to-end with mocked backends

incorrect: Module 1 ends at story 1.06 — each story has its own unit tests, no integration story.

rule: Module N story count = (unit stories) + 1 integration test story. No exceptions. The integration story is what tells you the module is shippable.


title: PRD Must Include Component Interface Contracts Section

axiom: Every multi-module Epic PRD MUST include a dedicated section defining the interface contracts between components/modules. Without explicit contracts, modules couple implicitly and become impossible to evolve independently.

correct: Section 10: Component Interface Contracts — Protocol classes for IL1Cache, IL2KnowledgeGraph, ITierRouter, IStagingArea, IOCCEngine, IShadowArena, IEpochRunner with full type signatures.

incorrect: Components interact with each other as needed — the code will make the interfaces clear.

rule: Interface contracts are PRD artifacts, not code artifacts. Write them in the PRD. Every consuming module imports only the Protocol — never the concrete class. This is the enforced decoupling boundary.


title: PRD Must Include A Wave Execution Plan For Parallel Swarm Firing

axiom: Every Genesis Epic PRD MUST include an explicit wave execution plan showing which modules fire in parallel and which are sequential. Dependency-unaware PRDs serialize what could be parallelized — wasting swarm capacity.

correct: Wave 1: Modules 1+2+3 simultaneously (no deps). Wave 2: Modules 4+5 simultaneously (need M1). Wave 3: Modules 6+7 simultaneously (need M1+M5). Wave 4a+4b: M8 then M9 (need all prior).

incorrect: Implement modules in order: 1, 2, 3, 4, 5, 6, 7, 8, 9.

rule: Build the dependency DAG before the first story. Identify which modules have no upstream deps — those are Wave 1. Every subsequent wave is gated only by its actual dependencies. Parallelism = velocity.


title: PRD Must Have A Global Verification Checklist Separate From Per-Story Tests

axiom: Every Genesis Epic PRD MUST include a Global Verification Checklist at the end — architectural gates that apply to ALL stories (no SQLite, no C: drive, OCC enforced, Immutable Kernel intact, etc). Per-story tests catch local bugs. Global gates catch systemic violations.

correct: Section 11: Global Verification Checklist — 6 categories: Code Quality Gates, Testing Gates, Architecture Gates, Performance Gates, 1000-Agent Scale Gates, Verification Stamp Format.

incorrect: Each story has its own tests — that's enough.

rule: Two-layer verification: (1) per-story test plan and (2) global architectural gates. Story-level tests pass ≠ system-correct. Global gates are the final check before any story is merged.


title: Blueprint First — PRD Second — Never Reverse

axiom: The source material for a Genesis PRD MUST be a pre-existing architecture blueprint document (Deep Think output, architecture map, Q&A sessions). A PRD written without a blueprint invents architecture — it does not translate it. Blueprint = WHAT and WHY. PRD = HOW and WHEN.

correct: Read GENESIS_PERSISTENT_CONTEXT_ARCHITECTURE_V2.md (651 lines, 7 Deep Think Q&A answers) in 3 chunks → absorb all architecture → then write PRD translating blueprint into executable stories.

incorrect: Write the PRD and figure out the architecture as you go.

rule: PRD author reads blueprint to 100% comprehension before writing story 1. Architecture decisions are CLOSED when PRD writing begins. PRD translates — it does not invent.


title: PRD Story Title Must Be Parseable As An Assignment Ticket

axiom: Every PRD story title MUST be parseable as a one-line agent assignment ticket. If a story title requires reading the story body to understand what to build, the title is wrong. Title format: [Story N.NN]: [Primary Artifact] — [Key Behavior]

correct: Story 6.04: OCCCommitEngine — 8-Step Coherence Flow | Story 3.02: VoyagerDefenseScorer — Severity Classification

incorrect: Story 6: Implement concurrency control | Story 3: Error handling

rule: Story title = agent ticket subject line. An agent reading only titles should understand the module's full scope. Vague titles hide scope and invite misinterpretation.


title: PRD Must Be Written In Append Mode — Never As One Giant Write

axiom: A Genesis Epic PRD (50+ stories) MUST be written in chunks using append mode — never as a single write. Single large writes fail partway and lose all progress. Append mode is incremental, verifiable, and recoverable. Write one module at a time, verify line count after each append.

correct: Write header (rewrite) → Module 1 (append, verify 350 lines) → Module 2 (append, verify 680 lines) → ... → Closing (append, verify 3147 lines). Each append confirms the file grew.

incorrect: Write entire 3000-line PRD as one operation.

rule: PRD write protocol: 1 chunk = 1 module. Verify appendPosition after each write. If a write fails, only one module is lost — not the entire PRD.