flowchart TD
    A[Input: SPEC Path] --> B[Find Latest Review Report]
    B --> C{Review Found?}
    C -->|No| D[Run doc-spec-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

    subgraph YAMLFix["YAML Structure Fixes"]
        K2 --> Y1[Parse YAML Blocks]
        Y1 --> Y2{YAML Valid?}
        Y2 -->|No| Y3[Repair YAML Structure]
        Y2 -->|Yes| Y4[Validate Schema Compliance]
        Y3 --> Y4
    end

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

def fix_spec_structure(spec_path: str) -> list[Fix]:
    """Fix SPEC structure violations."""
    fixes = []

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

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

    spec_id = match.group(1)
    slug = match.group(2)
    expected_folder = f"SPEC-{spec_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(spec_path, new_path)
        fixes.append(f"Moved {spec_path} to {new_path}")

        # Update upstream references in YAML file
        content = Path(new_path).read_text()
        updated_content = content.replace('../08_CTR/', '../../08_CTR/')
        updated_content = updated_content.replace('../07_REQ/', '../../07_REQ/')
        Path(new_path).write_text(updated_content)
        fixes.append(f"Updated relative links for nested folder structure")

    return fixes

undefined

**SPEC Configuration Template**:

```yaml

---

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

    # SPEC files: docs/09_SPEC/SPEC-01.md
    # Schema files: docs/09_SPEC/schemas/
    # Config files: docs/09_SPEC/config/

    if is_yaml_include(target_path):
        return fix_yaml_include(spec_location, target_path)
    elif is_schema_reference(target_path):
        return fix_schema_ref(spec_location, target_path)
    else:
        return calculate_relative_path(spec_location, target_path)

def generate_yaml_element_id(spec_id: str, yaml_path: list) -> str:
    """Generate element ID from YAML path.

    Example:
        spec_id: "SPEC-01"
        yaml_path: ["schemas", "definitions", "UserSchema"]
        returns: "SPEC-01.schemas.definitions.UserSchema"
    """
    return f"{spec_id}.{'.'.join(yaml_path)}"

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'),
    '"1.0.0"': f'"{calculate_version()}"',
}

<!-- Before -->

---

def calculate_drift_percentage(
    upstream_doc: str,
    spec_references: list,
    upstream_modified: datetime,
    spec_created: datetime
) -> float:
    """Calculate drift percentage between upstream and SPEC.

    Factors:
    - Line diff percentage in referenced sections
    - Number of new/removed requirements
    - Structural changes (new sections, moved content)
    - Time since last sync (decay factor)

    Returns:
        float: Drift percentage (0.0 - 100.0)
    """
    line_changes = count_line_changes(upstream_doc, spec_references)
    total_lines = count_referenced_lines(upstream_doc, spec_references)

    if total_lines == 0:
        return 0.0

    base_percentage = (line_changes / total_lines) * 100

    # Apply time decay factor (older drift = more significant)
    days_stale = (datetime.now() - spec_created).days
    decay_factor = min(1.0 + (days_stale / 30) * 0.1, 1.5)

    return min(base_percentage * decay_factor, 100.0)

def generate_spec_id(
    spec_number: int,
    component: str,
    sub_spec: int
) -> str:
    """Generate SPEC ID following SPEC-NN-COMPONENT-SS pattern.

    Args:
        spec_number: Main spec number (1-99)
        component: Component identifier (e.g., AUTH, API, DATA)
        sub_spec: Sub-spec number (1-99)

    Returns:
        str: Formatted SPEC ID

    Example:
        generate_spec_id(1, "AUTH", 13) -> "SPEC-01-AUTH-13"
    """
    return f"SPEC-{spec_number:02d}-{component.upper()}-{sub_spec:02d}"

<!-- DEPRECATED: 2026-02-10 - Superseded by SPEC-01-AUTH-14 -->
<!-- Reason: Major upstream drift (>15%) triggered regeneration -->
<!-- Archive: archive/SPEC-01-AUTH-13_v1.2.0_20260210.md -->
---
title: "[DEPRECATED] SPEC-01-AUTH-13: Authentication Flow"
status: deprecated
superseded_by: SPEC-01-AUTH-14
---

undefined

total_drift: 20.85
trigger_tier: 3

undefined

{
  "cache_version": "2.0",
  "last_updated": "2026-02-10T16:00:00",
  "specs": {
    "SPEC-01-AUTH-13": {
      "current_version": "1.2.0",
      "created": "2026-02-05T10:00:00",
      "last_sync": "2026-02-08T14:30:00",
      "upstream_refs": {
        "REQ-01.md": {
          "last_known_hash": "a1b2c3d4",
          "last_modified": "2026-02-08T09:00:00",
          "sections_tracked": ["3.1", "3.2", "5.4"]
        },
        "CTR-01-API.yaml": {
          "last_known_hash": "e5f6g7h8",
          "last_modified": "2026-02-07T16:00:00",
          "endpoints_tracked": ["/auth/login", "/auth/refresh"]
        }
      },
      "merge_history": [
        {
          "date": "2026-02-06T11:00:00",
          "tier": 1,
          "drift_percentage": 3.2,
          "version_before": "1.0.0",
          "version_after": "1.0.1",
          "changes_merged": ["REQ-01.md: Updated validation rules"]
        },
        {
          "date": "2026-02-08T14:30:00",
          "tier": 2,
          "drift_percentage": 8.5,
          "version_before": "1.0.1",
          "version_after": "1.1.0",
          "changes_merged": [
            "REQ-01.md: Added new requirement REQ-01.28.05",
            "CTR-01-API.yaml: Modified /auth/refresh response"
          ],
          "changelog_file": "changelogs/SPEC-01-AUTH-13_v1.1.0_changelog.md"
        }
      ],
      "downstream_documents": {
        "tspec": ["TSPEC-01-AUTH-13"],
        "tasks": ["TASKS-01-AUTH-13"]
      }
    }
  }
}

undefined

undefined

<!-- DRIFT-MERGED: Tier 1 | REQ-01.md | 3.2% | 2026-02-08 | v1.0.0 -> v1.0.1 -->
@req: [REQ-01.28.01](../07_REQ/REQ-01.md#req-01-28-01) @version:1.3.0

<!-- DRIFT-MERGED: Tier 2 | CTR-01-API.yaml | 8.5% | 2026-02-08 | v1.0.1 -> v1.1.0 -->
<!-- See: changelogs/SPEC-01-AUTH-13_v1.1.0_changelog.md -->
@ctr: [CTR-01-API](../08_CTR/CTR-01-API.md) @version:2.1.0

<!-- DRIFT-ARCHIVED: Tier 3 | 20.85% | 2026-02-10 | Regeneration triggered -->
<!-- Archive: archive/SPEC-01-AUTH-13_v1.2.0_20260210.md -->
<!-- New SPEC: SPEC-01-AUTH-14 -->

def find_yaml_blocks(content: str) -> list:
    """Find all YAML code blocks in markdown content."""
    pattern = r'```ya?ml\n(.*?)```'
    return re.findall(pattern, content, re.DOTALL)

undefined

undefined

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

---

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