1. Parse input: Extract TYPE and NN from "{TYPE}-{NN}"
2. Determine action:
   - IF TYPE == "SYS": Review Mode
   - ELSE IF TYPE == "ADR": Generate/Find Mode
   - ELSE: Error (invalid type for this autopilot)
3. For Generate/Find Mode:
   - Check: Does SYS-{NN} exist in docs/06_SYS/?
   - IF exists: Switch to Review Mode for SYS-{NN}
   - ELSE: Proceed with Generation from ADR-{NN}

undefined

undefined

undefined

undefined

Input: ADR-01
├── Detected Type: ADR (upstream)
├── Expected SYS: SYS-01
├── SYS Exists: Yes → docs/06_SYS/SYS-01_f1_iam/
└── Action: REVIEW MODE - Running doc-sys-reviewer on SYS-01

Input: ADR-05
├── Detected Type: ADR (upstream)
├── Expected SYS: SYS-05
├── SYS Exists: No
└── Action: GENERATE MODE - Creating SYS-05 from ADR-05

Input: SYS-03
├── Detected Type: SYS (self)
└── Action: REVIEW MODE - Running doc-sys-reviewer on SYS-03

flowchart TD
    subgraph Phase1["Phase 1: ADR Analysis"]
        A[Start] --> B[Read ADR Documents]
        B --> C[Extract Architecture Decisions]
        C --> D[Identify System Constraints]
        D --> E[Catalog Technical Requirements]
    end

    subgraph Phase2["Phase 2: SYS Readiness Check"]
        E --> F[Check ADR SYS-Ready Scores]
        F --> G{All ADRs >= 90%?}
        G -->|No| H[Flag ADRs Below Threshold]
        H --> I[Report Missing Elements]
        I --> J[Abort or Continue with Warnings]
        G -->|Yes| K[Mark ADRs Ready for SYS]
    end

    subgraph Phase3["Phase 3: SYS Generation"]
        K --> L{Next ADR Topic}
        L --> M[Load SYS Template]
        M --> N[Generate Document Control]
        N --> O[Generate Functional Requirements]
        O --> P[Generate Quality Attributes]
        P --> Q[Generate Interface Specifications]
        Q --> R[quality-advisor: Real-time Feedback]
        R --> S[Generate Remaining Sections]
        S --> T[Add Cumulative Tags]
        T --> U[Write SYS Files]
    end

    subgraph Phase4["Phase 4: SYS Validation"]
        U --> V[Run doc-sys-validator]
        V --> W{REQ-Ready >= 90%?}
        W -->|No| X[Auto-Fix SYS Issues]
        X --> Y[Re-validate SYS]
        Y --> W
        W -->|Yes| Z[Mark SYS Validated]
    end

    subgraph Phase5["Phase 5: Review & Fix Cycle"]
        Z --> ZA[Run doc-sys-reviewer]
        ZA --> ZB{Score >= 90?}
        ZB -->|No| ZC[Run doc-sys-fixer]
        ZC --> ZD{Iteration < Max?}
        ZD -->|Yes| ZA
        ZD -->|No| ZE[Flag Manual Review]
        ZB -->|Yes| ZF[Verify Quality Checks]
        ZE --> ZF
        ZF --> AA{More ADR Topics?}
        AA -->|Yes| L
        AA -->|No| AB[Check All SYS Complete]
        AB --> AC[Verify Cross-SYS Consistency]
        AC --> AD[Update Traceability Matrix]
        AD --> AE[Generate Summary Report]
    end

    AE --> AF[Complete]

undefined

**Required ADR Content per Topic**:

| ADR | Topic Category | Key Content for SYS |
|-----|----------------|---------------------|
| ADR-01 | Infrastructure | Compute, networking, scaling constraints |
| ADR-02 | Data Architecture | Storage, data flow, persistence requirements |
| ADR-03 | Integration | API patterns, messaging, protocol requirements |
| ADR-04 | Security | Authentication, authorization, encryption requirements |
| ADR-05 | Observability | Logging, monitoring, alerting requirements |
| ADR-06 | AI/ML | Model requirements, inference constraints |
| ADR-07 | Technology Selection | Framework, language, tool constraints |

**Output**: System requirements catalog with ADR-derived constraints and technical requirements.

def check_adr_readiness(adr_list: list) -> dict:
    """
    Check SYS-Ready scores for all ADR documents.

    Returns:
        dict with 'ready' (list of ADRs >= 90%)
        and 'not_ready' (list of ADRs < 90% with issues)
    """
    ready = []
    not_ready = []

    for adr in adr_list:
        score = extract_sys_ready_score(adr)
        if score >= 90:
            ready.append(adr)
        else:
            not_ready.append({
                'adr': adr,
                'score': score,
                'issues': identify_missing_elements(adr)
            })

    return {'ready': ready, 'not_ready': not_ready}

docs/06_SYS/SYS-01_f1_iam/
├── SYS-01.00_index.md                    # Index with REQ-Ready score
├── SYS-01.01_authentication.md           # Auth capabilities
├── SYS-01.02_authorization.md            # Authz capabilities
├── SYS-01.03_session_management.md       # Session handling
├── SYS-01.04_audit_logging.md            # Audit requirements
└── SYS-01.05_mfa_integration.md          # MFA requirements

---
parent_doc: SYS-01
capability_id: SYS-01.01
capability_name: Authentication
version: 1.0.0
status: Draft
---

---

undefined

undefined

REQ-Ready Score: ✅ 94% (Target: ≥90%)

Category Breakdown:
├── Functional Decomposition:  24/25 ✅
├── Quality Attributes:        20/20 ✅
├── Interface Specifications:  18/20 🟡
├── Data Management:           14/15 ✅
├── Testing Requirements:       9/10 ✅
└── Traceability:              10/10 ✅

External Dependencies:
├── Dependencies Documented:   ✅ 6/6
├── Fallback Strategies:       ✅ 6/6
└── Threshold References:      ✅ 12/12

python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/SYS-NN_{slug}/SYS-NN_{slug}.md --verbose

LOOP (max 3 iterations):
  1. Run doc-sys-validator
  2. IF errors found: Apply auto-fixes
  3. IF warnings found: Review and address if critical
  4. IF REQ-Ready Score < 90%: Enhance sections
  5. IF clean: Mark VALIDATED, proceed
  6. IF max iterations: Log issues, flag for manual review

flowchart TD
  A[Phase 5 Start] --> B[Run doc-sys-audit]
  B --> C[Generate Combined Audit Report]
    C --> D{Review Score >= 90?}

    D -->|Yes| E[PASS - Proceed to Final Checks]
    D -->|No| F{Iteration < Max?}

    F -->|Yes| G[Run doc-sys-fixer]
    G --> H[Apply Fixes]
    H --> I[Generate Fix Report]
    I --> J[Increment Iteration]
    J --> B

    F -->|No| K[Flag for Manual Review]
    K --> L[Generate Final Report with Remaining Issues]
    L --> E

/doc-sys-audit SYS-NN

/doc-sys-fixer SYS-NN --revalidate

/doc-sys-audit SYS-NN

Iteration 1:
  Review v001: Score 86 (3 errors, 5 warnings)
  Fix v001: Fixed 6 issues, updated 2 tables

Iteration 2:
  Review v002: Score 93 (0 errors, 3 warnings)
  Status: PASS (score >= 90)

4. **REQ-Ready Report**:

5. **Summary Report Generation**:

---

undefined

undefined

undefined

undefined

/doc-sys-autopilot all --dry-run

undefined

undefined

**Review Process**:

```mermaid
flowchart TD
    A[Input: Existing SYS] --> B[Load SYS Documents]
    B --> C[Run Validation Checks]
    C --> D[Calculate REQ-Ready Score]
    D --> E[Check 6-Category Breakdown]
    E --> F[Validate External Dependencies]
    F --> G[Identify Issues]
    G --> H{Generate Report}
    H --> I[Fixable Issues List]
    H --> J[Manual Review Items]
    H --> K[Score Breakdown]
    I --> L[Output: Review Report]
    J --> L
    K --> L

undefined

**Review Configuration**:

```yaml
review_mode:
  enabled: true
  checks:
    - structure_validation      # Document control, sections
    - element_id_compliance     # SYS.NN.TT.SS format
    - threshold_references      # @threshold format and validity
    - external_dependencies     # Table, fallback, timeouts
    - quality_attributes        # 6 categories present
    - cumulative_tags           # 5 upstream tags
    - score_calculation         # REQ-Ready score
    - modular_structure         # If >25KB
  output:
    format: markdown           # markdown, json, html
    include_line_numbers: true
    include_fix_suggestions: true
  thresholds:
    pass: 90
    warning: 85
    fail: 0

undefined

**Fix Process**:

```mermaid
flowchart TD
    A[Input: Existing SYS] --> B[Run Review Mode]
    B --> C[Identify Fixable Issues]
    C --> D{Backup Enabled?}
    D -->|Yes| E[Create Backup]
    D -->|No| F[Skip Backup]
    E --> G[Apply Fixes by Category]
    F --> G

    subgraph FixCategories["Fix Categories"]
        G --> H[Element ID Fixes]
        G --> I[Threshold Fixes]
        G --> J[Dependencies Fixes]
        G --> K[Structure Fixes]
        G --> L[Traceability Fixes]
    end

    H --> M[Preserve Manual Content]
    I --> M
    J --> M
    K --> M
    L --> M

    M --> N[Re-validate]
    N --> O{Score Improved?}
    O -->|Yes| P[Generate Fix Report]
    O -->|No| Q[Log Warnings]
    Q --> P
    P --> R[Output: Fixed SYS + Report]

undefined

**Fix Configuration**:

```yaml
fix_mode:
  enabled: true
  backup:
    enabled: true
    location: "tmp/backup/"
    retention_days: 7

  fix_categories:
    element_ids: true        # Legacy ID conversion
    thresholds: true         # @threshold references
    dependencies: true       # External dependencies table
    structure: true          # Document sections
    traceability: true       # Cumulative tags

  preservation:
    functional_requirements: true   # Never modify FR content
    quality_attributes: true        # Never modify QA targets
    interface_specs: true           # Never modify interface content
    comments: true                  # Preserve user comments

  validation:
    re_validate_after_fix: true
    require_score_improvement: false
    max_fix_iterations: 3

  element_id_migration:
    FR_XXX_to_SYS_NN_01_SS: true   # FR-001 → SYS.01.01.01
    QA_XXX_to_SYS_NN_02_SS: true   # QA-001 → SYS.01.02.01
    SR_XXX_to_SYS_NN_26_SS: true   # SR-001 → SYS.01.26.01

def handle_error(error_type: str, context: dict) -> Action:
    match error_type:
        case "ADR_SYS_READY_LOW":
            return Action.ABORT_WITH_MESSAGE
        case "ADR_NOT_FOUND":
            return Action.SKIP_OR_ABORT
        case "VALIDATION_FAILURE":
            if context["retry_count"] < 3:
                return Action.AUTO_FIX_RETRY
            return Action.FLAG_MANUAL_REVIEW
        case "REQ_READY_LOW":
            return Action.ENHANCE_SECTIONS
        case _:
            return Action.FLAG_MANUAL_REVIEW

undefined

undefined

For SYS batch of 7 ADR-derived documents:
  Chunk 1: SYS-01, SYS-02, SYS-03 → Complete → Summary
  [Context compaction opportunity]
  Chunk 2: SYS-04, SYS-05, SYS-06 → Complete → Summary
  [Context compaction opportunity]
  Chunk 3: SYS-07 → Complete → Summary

undefined

---

undefined

undefined

undefined

undefined

undefined

  - name: Run SYS Autopilot
    run: |
      /doc-sys-autopilot all

  - name: Upload Validation Report
    uses: actions/upload-artifact@v4
    with:
      name: sys-validation
      path: tmp/sys_validation_report.json

---