flowchart TD
    A[Input: BRD Path] --> B[Load BRD Files]
    B --> C{Sectioned or Monolithic?}

    C -->|Sectioned| D[Load All Section Files]
    C -->|Monolithic| E[Load Single File]

    D --> F0[Check #0: Structure Compliance]
    E --> F0

    F0 --> F0a{Nested Folder Valid?}
    F0a -->|No| F0b[FAIL - BLOCKING]
    F0a -->|Yes| F[Run Review Checks]

    subgraph Review["Review Checks"]
        F --> G[1. Link Integrity]
        G --> H[2. Requirement Completeness]
        H --> I[3. ADR Topic Coverage]
        I --> J[4. Placeholder Detection]
        J --> K[5. Traceability Tags]
        K --> L[6. Section Completeness]
        L --> M[7. Strategic Alignment]
        M --> M2[8. Naming Compliance]
        M2 --> M3[9. Upstream Drift Detection]
    end

    M3 --> N{Issues Found?}
    N -->|Yes| O[Categorize Issues]
    O --> P{Auto-Fixable?}
    P -->|Yes| Q[Apply Auto-Fixes]
    Q --> R[Re-run Affected Checks]
    P -->|No| S[Flag for Manual Review]
    R --> N
    S --> T[Generate Report]
    N -->|No| T
    T --> U[Calculate Review Score]
    U --> V{Score >= Threshold?}
    V -->|Yes| W[PASS]
    V -->|No| X[FAIL with Details]

1. Check document is inside a nested folder: docs/01_BRD/BRD-NN_{slug}/
2. Verify folder name matches BRD ID pattern: BRD-NN_{slug}
3. Verify file name matches folder: BRD-NN_{slug}.md or BRD-NN.N_*.md
4. Parent path must be: docs/01_BRD/

docs/01_BRD/
├── BRD-01_f1_iam/
│   ├── BRD-01_f1_iam.md           ✓ Valid (monolithic)
│   ├── BRD-01.R_review_report_v001.md
│   └── .drift_cache.json
├── BRD-02_f2_session/
│   ├── BRD-02.0_index.md          ✓ Valid (sectioned)
│   ├── BRD-02.1_core.md
│   └── BRD-02.2_requirements.md

docs/01_BRD/
├── BRD-01_f1_iam.md               ✗ NOT in nested folder

{
  "schema_version": "1.0",
  "document_id": "BRD-01",
  "document_version": "1.0",
  "last_reviewed": "2026-02-10T17:00:00",
  "reviewer_version": "1.4",
  "upstream_documents": {
    "../../00_REF/foundation/F1_IAM_Technical_Specification.md": {
      "hash": "sha256:a1b2c3d4e5f6g7h8i9j0...",
      "last_modified": "2026-02-10T15:34:26",
      "file_size": 50781,
      "version": "1.0",
      "sections_tracked": ["#3-authentication", "#4-authorization", "#5-user-profile"]
    },
    "../../00_REF/foundation/GAP_Foundation_Module_Gap_Analysis.md": {
      "hash": "sha256:k1l2m3n4o5p6q7r8s9t0...",
      "last_modified": "2026-02-10T15:34:21",
      "file_size": 4730,
      "version": "1.0",
      "sections_tracked": ["#f1-iam-gaps"]
    }
  },
  "review_history": [
    {
      "date": "2026-02-10T16:30:00",
      "score": 97,
      "drift_detected": false,
      "report_version": "v002"
    }
  ]
}

PHASE 1: Load Cache (if exists)
=========================================
1. Check for .drift_cache.json in BRD folder
2. If exists:
   - Load cached hashes and metadata
   - Set detection_mode = "hash_comparison"
3. If not exists:
   - Set detection_mode = "timestamp_only"
   - Will create cache at end of review

PHASE 2: Detect Drift
=========================================
For each upstream reference in BRD:

  A. Extract reference:
     - @ref: tags → [path, section anchor]
     - @strategy: tags → [document ID]
     - Links to ../00_REF/ → [path]
     - Traceability table upstream artifacts → [path]

  B. Resolve and validate:
     - Resolve path to absolute file path
     - Check file exists (skip if covered by Check #1)
     - Get file stats: mtime, size

  C. Compare (based on detection_mode):

     IF detection_mode == "hash_comparison":
       - Compute SHA-256 hash of current file content
       - Compare to cached hash
       - IF hash differs:
           - Calculate change_percentage
           - Flag as CONTENT_DRIFT (REV-D002)
           - IF change > 20%: Flag as CRITICAL (REV-D005)

     ELSE (timestamp_only):
       - Compare file mtime > BRD last_updated
       - IF mtime > BRD date:
           - Flag as TIMESTAMP_DRIFT (REV-D001)

  D. Check version field (if YAML frontmatter):
     - Extract version from upstream doc
     - Compare to cached version
     - IF version incremented: Flag REV-D003

PHASE 3: Update Cache (MANDATORY)
=========================================
1. Compute SHA-256 hash for ALL upstream documents
2. Create/update .drift_cache.json with:
   - Current hashes
   - Current timestamps
   - Current file sizes
   - Review metadata
3. Append to review_history array

import hashlib
from pathlib import Path

def compute_file_hash(file_path: str) -> str:
    """Compute SHA-256 hash of file content."""
    sha256 = hashlib.sha256()
    with open(file_path, 'rb') as f:
        for chunk in iter(lambda: f.read(8192), b''):
            sha256.update(chunk)
    return f"sha256:{sha256.hexdigest()}"

def compute_section_hash(file_path: str, section_anchor: str) -> str:
    """Compute hash of specific section (for anchor references)."""
    content = Path(file_path).read_text()
    # Extract section from anchor to next heading
    section_pattern = f"#{section_anchor.lstrip('#')}"
    # ... section extraction logic ...
    section_content = extract_section(content, section_pattern)
    return f"sha256:{hashlib.sha256(section_content.encode()).hexdigest()}"

def calculate_change_percentage(old_hash: str, new_content: str) -> float:
    """Estimate change percentage using content diff."""
    # Use difflib to calculate similarity ratio
    import difflib
    # ... comparison logic ...
    return change_percentage

undefined

---

undefined

undefined

1. Scan folder for pattern: BRD-NN.R_review_report_v*.md
2. Extract highest version number (N)
3. Create new file with version (N + 1)

docs/01_BRD/BRD-03_f3_observability/
├── BRD-03.R_review_report_v001.md    # First review
├── BRD-03.R_review_report_v002.md    # After fixes
└── BRD-03.R_review_report_v003.md    # Final review

undefined

See `REVIEW_DOCUMENT_STANDARDS.md` for complete requirements.

---

flowchart LR
    A[Phase 4: Validation] --> B[Phase 5: Final Review]
    B --> C{doc-brd-reviewer}
    C --> D[Phase 6: Continue]