# Governance Ruleset Export Template - COMPREHENSIVE
# This file serves as a template for exporting complete governance configurations
# Version: 2.0 (Expanded with all governance dimensions)
# Format: YAML
#
# This template includes ALL material governance dimensions that should be forkable:
# 1. Action tiers (including security and emergency tiers)
# 2. Nested multisig teams
# 3. Governance review policy
# 4. Repository layers
# 5. Tier classification rules
# 6. Emergency procedures
# 7. Cross-layer rules
# 8. Governance fork settings
# 9. Validation requirements

# Export metadata
export_metadata:
  version: "2.0"
  ruleset_id: "btcdecoded-governance-v2"
  ruleset_version: "2.0.0"
  created_at: "2025-01-01T00:00:00Z"
  exported_by: "governance-app"
  source_repository: "BTCDecoded/governance"
  commit_hash: "abc123def456"
  export_tool_version: "0.2.0"
  signature: null
  verification_url: null

# ============================================================================
# DIMENSION 1: ACTION TIERS
# ============================================================================

action_tiers:
  # Standard tiers
  tier_1_routine:
    name: "Routine Maintenance"
    signatures:
      required: 3
      total: 5
    review_period_days: 7
    emergency_override: false
    description: "Bug fixes, documentation, performance optimizations"
    requirements:
      - "Non-consensus changes only"
      - "No new features"
      - "No breaking changes"

  tier_2_features:
    name: "Feature Changes"
    signatures:
      required: 4
      total: 5
    review_period_days: 30
    emergency_override: false
    requires_specification: true
    description: "New RPC methods, P2P changes, wallet features"
    requirements:
      - "Must include technical specification"
      - "Must include test coverage"
      - "Must include documentation"

  tier_3_consensus_adjacent:
    name: "Consensus-Adjacent"
    signatures:
      required: 5
      total: 5
    review_period_days: 90
    emergency_override: false
    requires_specification: true
    requires_audit: true
    description: "Changes affecting consensus validation code"
    requirements:
      - "Maintainer 5-of-5 and extended review"
      - "Must include consensus impact analysis"
      - "Must include security audit"

  tier_4_emergency:
    name: "Emergency Actions"
    signatures:
      required: 4
      total: 5
    review_period_days: 0
    emergency_override: true
    requires_post_mortem: true
    description: "Critical security patches, network-threatening bugs"
    requirements:
      - "Maintainer coordination and rapid signatures"
      - "Post-mortem required"
      - "Evidence of criticality required"

  tier_5_governance:
    name: "Governance Changes"
    signatures:
      required: 5
      total: 5
    review_period_days: 180
    emergency_override: false
    requires_public_comment: true
    requires_rationale: true
    description: "Changes to governance rules themselves"
    requirements:
      - "Extended public comment and documented rationale"
      - "Optional ecosystem/miner feedback may inform maintainers (non-binding)"

  # Security-specific tiers
  security_critical:
    name: "Security-Critical Changes"
    signatures:
      required: 7
      total: 7
    review_period_days: 180
    emergency_override: false
    requires_security_audit: true
    requires_formal_verification: true
    requires_cryptography_expert: true
    requires_public_comment: true
    requires_rationale: true
    description: "Changes affecting P0 security controls"
    additional_requirements:
      - "All affected P0 controls must be certified"
      - "No placeholder implementations in diff"
      - "Formal verification proofs passing"
      - "Security audit report attached to PR"
      - "Cryptographer approval required"

  cryptographic:
    name: "Cryptographic Operations"
    signatures:
      required: 6
      total: 7
    review_period_days: 90
    emergency_override: false
    requires_cryptography_expert: true
    requires_formal_verification: true
    description: "Changes to cryptographic operations, signature verification, key management"
    additional_requirements:
      - "Cryptographer approval required"
      - "Test vectors from standard specifications"
      - "Side-channel analysis performed"
      - "Formal verification proofs passing"

  security_enhancement:
    name: "Security Enhancement"
    signatures:
      required: 5
      total: 7
    review_period_days: 30
    emergency_override: false
    requires_security_review: true
    description: "Changes affecting P1 security controls"
    additional_requirements:
      - "Security review by maintainer"
      - "Comprehensive test coverage"
      - "No placeholder implementations"

# ============================================================================
# DIMENSION 2: NESTED MULTISIG TEAMS
# ============================================================================

nested_multisig_teams:
  # Team structure (customizable - could be 5 teams, 7 teams, 10 teams, etc.)
  teams:
    - id: team-1
      name: "Constitutional Team"
      description: "Layer 1-2 changes (Orange Paper, Consensus Proof)"
      maintainers:
        - github: maintainer1
          public_key: 0335573cdcac8f622dddc6a6799050d3739b016f389b0c74f954e27c9d07797363
          role: cryptographer
          added: 2025-01-01
          status: active
        # ... all maintainers in team

  # Team consensus requirements
  team_consensus:
    description: "Each team requires internal consensus"
    threshold_per_team: 6  # Could be 5-of-7, 4-of-5, etc.
    total_per_team: 7  # Could be 5, 7, 9, etc.

  # Inter-team consensus requirements
  inter_team_consensus:
    description: "Top level requires teams consensus"
    threshold_teams: 6  # Could be 4-of-5, 5-of-7, etc.
    total_teams: 7  # Could be 5, 7, 9, etc.

  # Tier requirements (using nested multisig)
  tier_requirements:
    tier_1:
      teams_required: 4
      maintainers_per_team: 5
      description: "Routine maintenance"
    tier_2:
      teams_required: 5
      maintainers_per_team: 6
      description: "Feature changes"
    tier_3:
      teams_required: 6
      maintainers_per_team: 6
      description: "Consensus-adjacent"
    tier_4:
      teams_required: 5
      maintainers_per_team: 5
      description: "Emergency actions"
    tier_5:
      teams_required: 7
      maintainers_per_team: 6
      description: "Constitutional changes"

  # Team membership criteria
  membership_criteria:
    adding_to_team:
      team_approval: "6-of-7"
      inter_team_approval: "4-of-7 teams"
    removing_from_team:
      team_approval: "6-of-7"  # excluding subject
      inter_team_approval: "4-of-7 teams"

# ============================================================================
# DIMENSION 3: GOVERNANCE REVIEW POLICY
# ============================================================================

governance_review_policy:
  # Policy scope
  scope:
    on_platform_only: true  # Off-platform activity disregarded
    description: "Only on-platform activity related to maintainer role is considered"

  # Sanction thresholds
  sanctions:
    private_warning:
      threshold: "4-of-7"  # Team approval required
      response_deadline_days: 14
      appeal_threshold: "5-of-7"
    public_warning:
      threshold: "5-of-7"  # Team approval required
      improvement_period_days: 90
      extension_allowed: true
      max_extension_days: 30
      response_deadline_days: 30
      appeal_threshold: "6-of-7"
    removal:
      threshold: "6-of-7"  # Team + 4-of-7 teams
      response_deadline_days: 30
      appeal_threshold: "5-of-7 teams"

  # Time limits
  time_limits:
    response_deadline_days: 30
    resolution_deadline_days: 180
    appeal_deadline_days: 60
    mediation_period_days: 30
    max_extension_days: 90
    extension_approval_threshold: "5-of-7 teams"

  # Appeal process
  appeals:
    enabled: true
    deadline_days: 60
    overturn_threshold: "5-of-7 teams"
    auto_reactivate_on_grant: true

  # Mediation process
  mediation:
    enabled: true
    period_days: 30
    auto_fail_on_expiry: true
    applies_to:
      - "Non-security issues"
      - "Disputes between maintainers"
      - "Conflicts that could be resolved through discussion"
    does_not_apply_to:
      - "Security issues (immediate threat)"
      - "Active attacks"
      - "Key compromise"
      - "Ongoing fraud or theft"

  # Emergency removal
  emergency_removal:
    enabled: true
    threshold: "4-of-5"  # Emergency keyholders
    requires_formal_removal_within_days: 7

# ============================================================================
# DIMENSION 4: REPOSITORY LAYERS
# ============================================================================

repository_layers:
  layer_1_constitutional:
    name: "Constitutional Layer"
    repositories:
      - "blvm-spec"
    purpose: "Constitutional documents and mathematical specifications"
    signatures:
      required: 6
      total: 7
    review_period_days: 180
    consensus_review_period_days: 365  # Special for consensus changes
    maintainers:
      - "constitutional-maintainer-1"
      # ... all maintainers

  layer_2_constitutional:
    name: "Constitutional Layer"
    repositories:
      - "blvm-consensus"
    purpose: "Consensus proof implementations"
    signatures:
      required: 6
      total: 7
    review_period_days: 180
    consensus_review_period_days: 365
    verification:
      required: true
      enforceable: true
      override_allowed: false
      tools:
        - name: "blvm-spec-lock"
          command: "cargo spec-lock verify --crate-path ."
          required: true
        - name: "Proptest"
          command: "cargo test --all-features"
          required: true
      ci_workflow: ".github/workflows/verify.yml"
      blocking: true

  layer_3_implementation:
    name: "Implementation Layer"
    repositories:
      - "blvm-protocol"
    purpose: "Core protocol implementation"
    signatures:
      required: 4
      total: 5
    review_period_days: 90

  layer_4_application:
    name: "Application Layer"
    repositories:
      - "blvm-node"
      - "blvm"
    purpose: "Reference implementation and applications"
    signatures:
      required: 3
      total: 5
    review_period_days: 60

  layer_5_extension:
    name: "Extension Layer"
    repositories:
      - "blvm-sdk"
    purpose: "Developer tools and extensions"
    signatures:
      required: 2
      total: 3
    review_period_days: 14

# ============================================================================
# DIMENSION 5: TIER CLASSIFICATION RULES
# ============================================================================

tier_classification:
  classification_rules:
    tier_1_routine:
      confidence_threshold: 0.8
      file_patterns:
        - "docs/**"
        - "*.md"
        - "tests/**"
      keywords:
        - "fix typo"
        - "documentation"
        - "performance"
      exclude_patterns:
        - "consensus/**"
        - "validation/**"

    tier_2_features:
      confidence_threshold: 0.8
      file_patterns:
        - "rpc/**"
        - "wallet/**"
        - "p2p/**"
      keywords:
        - "feature"
        - "new"
        - "add"
      require_specification: true

    tier_3_consensus_adjacent:
      confidence_threshold: 0.9
      file_patterns:
        - "consensus/**"
        - "validation/**"
      keywords:
        - "consensus"
        - "validation"
      require_specification: true
      require_audit: true

    tier_4_emergency:
      confidence_threshold: 0.95
      keywords:
        - "emergency"
        - "critical"
        - "security"
        - "CVE"
      require_post_mortem: true

    tier_5_governance:
      confidence_threshold: 0.9
      file_patterns:
        - "governance/**"
        - "*.yml"
      keywords:
        - "governance"
        - "maintainer"
        - "signature"
      require_public_comment: true
      require_rationale: true

  confidence_scoring:
    file_pattern_match: 0.4
    keyword_match: 0.3
    title_analysis: 0.2
    description_analysis: 0.1
    boost_factors:
      multiple_file_matches: 0.1
      strong_keyword_matches: 0.1
      specification_present: 0.1
      audit_present: 0.1
    penalty_factors:
      conflicting_indicators: -0.2
      insufficient_evidence: -0.3
      unclear_intent: -0.1

  fallback:
    default_tier: 2
    confidence_threshold: 0.5
    require_manual_review: true

# ============================================================================
# DIMENSION 6: EMERGENCY PROCEDURES
# ============================================================================

emergency_procedures:
  emergency_tiers:
    tier_1_critical:
      name: "Critical Emergency"
      activation_threshold: "5-of-7"
      signature_threshold: "4-of-7"
      review_period_days: 0
      max_duration_days: 7
      extensions_allowed: 0
      requires_post_mortem: true
      post_mortem_deadline_days: 30
      requires_security_audit: true
      requires_public_disclosure: true

    tier_2_urgent:
      name: "Urgent Security Issue"
      activation_threshold: "5-of-7"
      signature_threshold: "5-of-7"
      review_period_days: 7
      max_duration_days: 30
      extensions_allowed: 1
      extension_duration_days: 30
      extension_threshold: "6-of-7"
      requires_post_mortem: true
      post_mortem_deadline_days: 60
      requires_public_disclosure: true

    tier_3_elevated:
      name: "Elevated Priority"
      activation_threshold: "5-of-7"
      signature_threshold: "6-of-7"
      review_period_days: 30
      max_duration_days: 90
      extensions_allowed: 2
      extension_duration_days: 30
      extension_threshold: "6-of-7"
      requires_post_mortem: true
      post_mortem_deadline_days: 90

  activation_process:
    step_1: "Emergency keyholder submits activation request with evidence"
    step_2: "Other emergency keyholders review and sign (5-of-7 required)"
    step_3: "Governance App activates tier and adjusts requirements"
    step_4: "Status checks reflect emergency parameters"
    step_5: "PRs merged under emergency rules"
    step_6: "Post-activation requirements tracked"
    step_7: "Automatic expiration at max_duration unless extended"

# ============================================================================
# DIMENSION 7: CROSS-LAYER RULES
# ============================================================================

cross_layer_rules:
  rules:
    - name: consensus_proof_sync
      description: "Orange Paper and Consensus Proof must stay synchronized"
      source_repo: blvm-spec
      source_pattern: consensus-rules/**
      target_repo: blvm-consensus
      target_pattern: proofs/**
      validation: corresponding_file_exists
      bidirectional: true
      blocking: true

    - name: protocol_engine_equivalence
      description: "Protocol Engine must reference specific Orange Paper version"
      source_repo: blvm-protocol
      source_pattern: consensus/**
      target_repo: blvm-spec
      validation: references_latest_version
      required_reference_format: "blvm-spec@v{VERSION}"
      blocking: true

    - name: reference_node_no_consensus
      description: "Reference Node cannot modify consensus rules"
      source_repo: blvm-node
      validation: no_consensus_modifications
      allowed_imports_only: true
      blocking: true

  dependencies:
    layer_1_to_lower:
      description: "Constitutional changes may require implementation updates"
      notification_required: true
      review_period_extension: 30
    layer_2_to_lower:
      description: "Consensus proof changes may require protocol updates"
      notification_required: true
      review_period_extension: 14
    layer_3_to_lower:
      description: "Protocol changes may require application updates"
      notification_required: true
      review_period_extension: 7

  emergency_cross_layer:
    description: "Emergency changes affecting multiple layers"
    requires_coordination: true
    notification_channels:
      - "maintainers"
      - "community"

# ============================================================================
# DIMENSION 8: GOVERNANCE FORK SETTINGS
# ============================================================================

governance_fork:
  fork_trigger_conditions:
    tier_3_sustained_objection:
      sustained_objection_days: 180  # Could be 90, 120, 365, etc.
      description: "Sustained maintainer or community objection to a Tier 3 ruleset track"
    maintainer_abuse:
      community_support_threshold: "documented supermajority of active contributors"
      description: "Maintainer abuse pattern with community support for reform"
    irreconcilable_disagreement:
      description: "Irreconcilable disagreement about governance direction"
      process: "Multiple governance approaches can coexist"

  fork_thresholds:
    minimum_adoption_percentage: 50.0
    minimum_node_count: 10
    minimum_hashpower_percentage: 30.0
    grace_period_days: 30

  adoption_measurement:
    measurement_period_days: 180  # Could be 90, 365, etc.
    primary_metric:
      node_and_operator_weight: 100.0
    daily_snapshots: true
    history_retention_days: 365

  resolution_scenarios:
    clear_winner_threshold: 90.0  # Could be 80%, 95%, etc.
    strong_majority_threshold: 60.0  # Could be 50%, 70%, etc.
    minority_threshold: 10.0  # Could be 5%, 15%, etc.
    sunset_period_days: 90  # Could be 30, 180, etc.
    extended_measurement_days: 360  # If 60-90% adoption, measure for additional 180 days

# ============================================================================
# DIMENSION 9: VALIDATION REQUIREMENTS
# ============================================================================

validation_requirements:
  signature_verification:
    algorithm: "secp256k1"
    message_format: "PR #{number} in {repository}"
    signature_format: "hex_encoded"

  review_periods:
    tier_1: 7
    tier_2: 30
    tier_3: 90
    tier_4: 0
    tier_5: 180

# ============================================================================
# MAINTAINERS (by layer - for backward compatibility)
# ============================================================================

maintainers:
  layer_1_2_constitutional:
    layer: 1
    governance_level: "constitutional"
    signature_threshold: "6-of-7"
    review_period_days: 180
    maintainers:
      - github: "maintainer1"
        public_key: "0335573cdcac8f622dddc6a6799050d3739b016f389b0c74f954e27c9d07797363"
        role: "cryptographer"
        status: "active"

  layer_3_implementation:
    layer: 3
    governance_level: "implementation"
    signature_threshold: "4-of-5"
    review_period_days: 90
    maintainers:
      - github: "maintainer3"
        public_key: "0x02[PLACEHOLDER_64_CHAR_HEX]"
        role: "developer"
        status: "active"

# ============================================================================
# REPOSITORIES (for backward compatibility)
# ============================================================================

repositories:
  orange_paper:
    layer: 1
    governance_level: "constitutional"
    signature_threshold: "6-of-7"
    review_period_days: 180
    action_tier: 3
    auto_classification:
      patterns:
        - "consensus-rules/**"
        - "validation/**"
      manual_override: true

  consensus_proof:
    layer: 2
    governance_level: "constitutional"
    signature_threshold: "6-of-7"
    review_period_days: 180
    action_tier: 3
    auto_classification:
      patterns:
        - "proofs/**"
        - "verification/**"
      manual_override: true

  protocol_engine:
    layer: 3
    governance_level: "implementation"
    signature_threshold: "4-of-5"
    review_period_days: 90
    action_tier: 2
    auto_classification:
      patterns:
        - "src/**"
        - "examples/**"
      manual_override: true