flowchart TD
    A[Input: CTR Path] --> B[Load CTR Files]
    B --> C{MD + YAML Present?}

    C -->|Both| D[Load Both Files]
    C -->|Single| E[Load Available File]

    D --> F[Run Review Checks]
    E --> F

    subgraph Review["Review Checks"]
        F --> G[1. Dual-File Consistency]
        G --> H[2. OpenAPI Compliance]
        H --> I[3. REQ Alignment]
        I --> J[4. Endpoint Coverage]
        J --> K[5. Security Definition]
        K --> L[6. Placeholder Detection]
        L --> M[7. Naming Compliance]
        M --> M2[8. Upstream Drift Detection]
    end

    M2 --> 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]

{
  "schema_version": "1.0",
  "last_updated": "2026-02-10T17:00:00",
  "documents": {
    "CTR-03-001": {
      "ctr_path": "docs/08_CTR/CTR-03-001_provider_api/CTR-03-001.md",
      "ctr_updated": "2026-02-10T14:30:00",
      "upstream_hashes": {
        "docs/07_REQ/REQ-03.md": {
          "full_hash": "a1b2c3d4e5f6...",
          "section_hashes": {
            "interfaces": "1a2b3c4d...",
            "external_apis": "5e6f7g8h..."
          },
          "last_checked": "2026-02-10T17:00:00"
        }
      }
    }
  }
}

Phase 1: Cache Initialization
  1. Check if docs/08_CTR/.drift_cache.json exists
  2. If not exists → create with schema_version: "1.0"
  3. Load cache into memory

Phase 2: Reference Extraction and Hash Comparison
  1. Extract all upstream references from CTR:
     - @req: tags → [path, section anchor]
     - Links to ../07_REQ/ → [path]
     - Traceability table upstream artifacts → [path]

  2. For each upstream reference:
     a. Resolve path to absolute file path
     b. Check file exists (already covered by Check #3)
     c. Compute SHA-256 hash of full file content
     d. If section anchor specified → compute section hash
     e. Compare hashes against cached values
     f. If hash differs → flag as DRIFT

Phase 3: Cache Update
  1. Update upstream_hashes with current values
  2. Set last_checked timestamp
  3. Write cache to disk
  4. Report cache status in output

import hashlib

def compute_file_hash(file_path: str) -> str:
    """Compute SHA-256 hash of file content."""
    with open(file_path, 'rb') as f:
        return hashlib.sha256(f.read()).hexdigest()

def compute_section_hash(file_path: str, section_anchor: str) -> str:
    """Compute SHA-256 hash of specific section content."""
    content = extract_section(file_path, section_anchor)
    return hashlib.sha256(content.encode()).hexdigest()

undefined

**Auto-Actions**:
- Create `.drift_cache.json` if not exists
- Update cache with current hashes after every review
- Add `[DRIFT]` marker to affected @req tags (optional)
- Generate drift summary in review report

**Configuration**:

| Setting | Default | Description |
|---------|---------|-------------|
| `cache_enabled` | true | Drift cache (Mandatory - cannot be disabled) |
| `drift_threshold_days` | 7 | Days before drift becomes Warning |
| `critical_threshold_days` | 30 | Days before drift becomes Error |
| `tracked_patterns` | `@req:` | Patterns to track for drift |

---

undefined

---

docs/08_CTR/CTR-03-001_provider_api/
├── CTR-03-001.md
├── CTR-03-001.yaml
├── CTR-03-001.R_review_report_v001.md    # First review
├── CTR-03-001.R_review_report_v002.md    # After fixes
└── .drift_cache.json

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