flowchart TD
    A[Input: ADR Path] --> B[Find Latest Review Report]
    B --> C{Review Found?}
    C -->|No| D[Run doc-adr-reviewer First]
    C -->|Yes| E[Parse Review Report]

    E --> F[Categorize Issues]

    subgraph FixPhases["Fix Phases"]
        F --> F0[Phase 0: Fix Structure Violations]
        F0 --> G[Phase 1: Create Missing Files]
        G --> H[Phase 2: Fix Broken Links]
        H --> I[Phase 3: Fix Element IDs]
        I --> J[Phase 4: Fix Content Issues]
        J --> K[Phase 5: Update References]
        K --> K2[Phase 6: Handle Upstream Drift]
    end

    K2 --> L[Write Fixed ADR]
    L --> M[Generate Fix Report]
    M --> N{Re-run Review?}
    N -->|Yes| O[Invoke doc-adr-reviewer]
    O --> P{Score >= Threshold?}
    P -->|No, iterations < max| F
    P -->|Yes| Q[COMPLETE]
    N -->|No| Q

def fix_adr_structure(adr_path: str) -> list[Fix]:
    """Fix ADR structure violations."""
    fixes = []

    filename = os.path.basename(adr_path)
    parent_folder = os.path.dirname(adr_path)

    # Extract ADR ID and slug from filename
    match = re.match(r'ADR-(\d+)_([^/]+)\.md', filename)
    if not match:
        return []  # Cannot auto-fix invalid filename

    adr_id = match.group(1)
    slug = match.group(2)
    expected_folder = f"ADR-{adr_id}_{slug}"

    # Check if already in nested folder
    if os.path.basename(parent_folder) != expected_folder:
        # Create nested folder
        new_folder = os.path.join(os.path.dirname(parent_folder), expected_folder)
        os.makedirs(new_folder, exist_ok=True)

        # Move file
        new_path = os.path.join(new_folder, filename)
        shutil.move(adr_path, new_path)
        fixes.append(f"Moved {adr_path} to {new_path}")

        # Update upstream links in moved file
        content = Path(new_path).read_text()
        updated_content = content.replace('../04_BDD/', '../../04_BDD/')
        updated_content = updated_content.replace('../03_EARS/', '../../03_EARS/')
        updated_content = updated_content.replace('../01_BRD/', '../../01_BRD/')
        Path(new_path).write_text(updated_content)
        fixes.append(f"Updated relative links for nested folder structure")

    return fixes

---
title: "ADR-00: Architecture Decision Records Index"
tags:
  - adr
  - index
  - reference
custom_fields:
  document_type: index
  artifact_type: ADR-REFERENCE
  layer: 5
---

**Architecture Placeholder Template**:

```markdown
---
title: "Architecture Document: [Component Name]"
tags:
  - architecture
  - reference
custom_fields:
  document_type: architecture
  status: placeholder
  created_by: doc-adr-fixer
---

---

def fix_link_path(adr_location: str, target_path: str) -> str:
    """Calculate correct relative path based on ADR location."""

    # Monolithic ADR: docs/05_ADR/ADR-01.md
    # Sectioned ADR: docs/05_ADR/ADR-01_slug/ADR-01.3_section.md

    if is_sectioned_adr(adr_location):
        # Need to go up one more level
        return "../" + calculate_relative_path(adr_location, target_path)
    else:
        return calculate_relative_path(adr_location, target_path)

undefined

---

replacements = {
    'YYYY-MM-DDTHH:MM:SS': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
    'YYYY-MM-DD': datetime.now().strftime('%Y-%m-%d'),
    'MM/DD/YYYY': datetime.now().strftime('%m/%d/%Y'),
    '[Current date]': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
    '[Status]': 'Proposed',
}

undefined

---

def calculate_drift_percentage(current_hash: str, upstream_hash: str,
                                current_content: str, upstream_content: str) -> float:
    """Calculate percentage of content change between versions."""
    if current_hash == upstream_hash:
        return 0.0

    # Line-based diff calculation
    current_lines = set(current_content.strip().split('\n'))
    upstream_lines = set(upstream_content.strip().split('\n'))

    added = upstream_lines - current_lines
    removed = current_lines - upstream_lines
    total_changes = len(added) + len(removed)
    total_lines = max(len(current_lines), len(upstream_lines), 1)

    return (total_changes / total_lines) * 100

<!-- Before -->
@ref: BDD-01.09.03 (v1.2.0)

<!-- After (auto-merged) -->
@ref: BDD-01.09.03 (v1.2.1)
<!-- Tier 1 auto-merge: Minor upstream update (2.3% change) - 2026-02-10 -->

undefined

---

undefined

**Archive Manifest Format** (`ADR-NN_archive_manifest.json`):

```json
{
  "archive_version": "1.0",
  "archive_date": "2026-02-10T16:00:00",
  "archived_adr": "ADR-01",
  "archived_version": "1.1.0",
  "new_version": "2.0.0",
  "trigger": {
    "type": "tier_3_drift",
    "upstream_document": "BDD-01.feature",
    "change_percentage": 23.5,
    "upstream_version_before": "1.2.0",
    "upstream_version_after": "2.0.0"
  },
  "superseded_decisions": [
    {
      "id": "ADR-01-05",
      "title": "Authentication Token Strategy",
      "superseded_by": "ADR-01-15",
      "reason": "Upstream BDD restructured authentication flow"
    },
    {
      "id": "ADR-01-07",
      "title": "Session Management Approach",
      "superseded_by": "ADR-01-16",
      "reason": "New session requirements in BDD"
    }
  ],
  "preserved_decisions": [
    {
      "id": "ADR-01-01",
      "title": "Database Selection",
      "status": "unchanged",
      "carried_forward_as": "ADR-01-01"
    }
  ],
  "archive_location": "docs/05_ADR/archive/ADR-01_v1.1.0/"
}

{
  "cache_version": "2.0",
  "adr_id": "ADR-01",
  "adr_version": "1.1.0",
  "adr_updated": "2026-02-10T16:00:00",
  "drift_reviewed": "2026-02-10T16:00:00",
  "upstream_tracking": {
    "BDD": {
      "document": "../../04_BDD/BDD-01.feature",
      "tracked_version": "1.3.0",
      "content_hash": "a1b2c3d4e5f6...",
      "last_sync": "2026-02-10T16:00:00"
    }
  },
  "downstream_tracking": {
    "SYS": {
      "document": "../../06_SYS/SYS-01.md",
      "notified_version": "1.1.0",
      "notification_date": "2026-02-10T16:00:00"
    }
  },
  "merge_history": [
    {
      "date": "2026-02-10T16:00:00",
      "tier": 2,
      "change_percentage": 8.7,
      "upstream_document": "BDD-01.feature",
      "version_before": "1.0.1",
      "version_after": "1.1.0",
      "decisions_updated": ["ADR-01-01", "ADR-01-03"],
      "decisions_flagged": ["ADR-01-03"],
      "auto_merged": true
    },
    {
      "date": "2026-02-08T10:00:00",
      "tier": 1,
      "change_percentage": 2.3,
      "upstream_document": "BDD-01.feature",
      "version_before": "1.0.0",
      "version_after": "1.0.1",
      "decisions_updated": ["ADR-01-02"],
      "decisions_flagged": [],
      "auto_merged": true
    }
  ],
  "acknowledged_drift": [
    {
      "document": "BDD-01.feature",
      "acknowledged_date": "2026-02-07",
      "acknowledged_version": "1.1.5",
      "reason": "Reviewed - documentation-only changes, no ADR impact"
    }
  ]
}

flowchart TD
    A[Detect Upstream Drift] --> B[Calculate Change %]
    B --> C{Change < 5%?}

    C -->|Yes| D[Tier 1: Auto-Merge]
    D --> D1[Update @ref tags]
    D1 --> D2[Increment patch version]
    D2 --> D3[Log to drift cache]
    D3 --> Z[Complete]

    C -->|No| E{Change 5-15%?}

    E -->|Yes| F[Tier 2: Auto-Merge + Changelog]
    F --> F1[Apply Tier 1 actions]
    F1 --> F2[Generate changelog block]
    F2 --> F3[Mark REVIEW-SUGGESTED]
    F3 --> F4[Increment minor version]
    F4 --> F5[Log to merge history]
    F5 --> Z

    E -->|No| G[Tier 3: Archive + Regenerate]
    G --> G1[Create archive manifest]
    G1 --> G2[Archive current version]
    G2 --> G3[Mark decisions SUPERSEDED]
    G3 --> G4[Increment major version]
    G4 --> G5[Trigger regeneration]
    G5 --> G6[Notify downstream SYS]
    G6 --> H[Human Review Required]

<!-- Downstream notification added to SYS-01.md -->
<!-- ADR-DRIFT-NOTIFICATION: ADR-01 updated to v1.1.0 (2026-02-10) -->
<!-- Tier 2 merge: 8.7% upstream change from BDD-01.feature -->
<!-- Decisions potentially affecting this SYS: ADR-01-01, ADR-01-03 -->
<!-- Review recommended for: Section 4 (Authentication Design) -->

undefined

undefined

---
title: "ADR-NN.F: Fix Report v001"
tags:
  - adr
  - fix-report
  - quality-assurance
custom_fields:
  document_type: fix-report
  artifact_type: ADR-FIX
  layer: 5
  parent_doc: ADR-NN
  source_review: ADR-NN.R_review_report_v001.md
  fix_date: "YYYY-MM-DDTHH:MM:SS"
  fix_tool: doc-adr-fixer
  fix_version: "1.0"
---

---

flowchart LR
    subgraph Phase5["Phase 5: Review & Fix Cycle"]
        A[doc-adr-reviewer] --> B{Score >= 90?}
        B -->|No| C[doc-adr-fixer]
        C --> D{Iteration < Max?}
        D -->|Yes| A
        D -->|No| E[Flag for Manual Review]
        B -->|Yes| F[PASS]
    end