pr_compliance_checklist.yaml

# Critical blockers that MUST prevent code from reaching production
pr_compliances:
  - title: "Undocumented Timing Requirements"
    compliance_label: true
    objective: "Ensure all timing-critical code sections have documented cycle counts and execution times for PRU assembly or C code"
    success_criteria: |
      - "All macros and functions have documented PEAK cycles"
      - "Worst-case execution time (WCET) is specified"
      - "Real-time constraints are clearly documented"
      - "Timing validation test results are provided"
    failure_criteria: |
      - "Any timing-critical code without cycle count documentation"
      - "Missing WCET analysis for real-time functions"
      - "Undocumented timing assumptions"
      - "No timing validation evidence"

  - title: "Non-Deterministic Code Paths"
    compliance_label: true
    objective: "Ensure all code paths have predictable, bounded execution times for PRU assembly or C code"
    success_criteria: |
      - "All code paths have documented execution times"
      - "No variable-length operations in critical sections"
      - "Conditional branches have balanced timing"
      - "Interrupt handlers have bounded execution time"
    failure_criteria: |
      - "Code paths with unpredictable execution times"
      - "Variable-length loops in critical sections"
      - "Unbalanced conditional branches"
      - "Unbounded interrupt processing"

  - title: "Unbounded Loops"
    compliance_label: true
    objective: "Prevent infinite loops that could hang the PRU indefinitely unless explicitly marked via comment"
    success_criteria:
      - "All loops have maximum iteration limits"
      - "Timeout mechanisms implemented for wait conditions"
      - "Loop bounds are validated and documented"
      - "Error handling for timeout conditions"
    failure_criteria:
      - "Any loop without maximum iteration limit"
      - "Wait conditions without timeout"
      - "Recursive calls without depth limits"
      - "Polling loops without exit conditions"

  - title: "Register Corruption"
    compliance_label: true
    objective: "Ensure register state is preserved across function calls and interrupts"
    success_criteria: |
      - "All functions preserve caller's register state"
      - "Interrupt handlers save and restore context"
      - "Register usage is documented"
      - "No unintended register modifications"
    failure_criteria: |
      - "Functions that modify caller's registers without saving"
      - "Interrupt handlers without context preservation"
      - "Undocumented register side effects"
      - "Register aliasing conflicts"

  - title: "Memory Bounds Violations"
    compliance_label: true
    objective: "Prevent memory access outside allocated boundaries"
    success_criteria: |
      - "All memory accesses have bounds checking"
      - "Array indices are validated"
      - "Pointer arithmetic is bounds-checked"
      - "Memory allocation limits are enforced"
    failure_criteria: |
      - "Memory access without bounds checking"
      - "Unchecked array indexing"
      - "Pointer arithmetic without validation"
      - "Buffer overflow potential"

  - title: "Missing Critical Error Handling"
    compliance_label: true
    objective: "Ensure all critical operations have proper error handling"
    success_criteria: |
      - "All critical API calls check return values"
      - "Error conditions are properly handled"
      - "System state is preserved on errors"
      - "Error recovery mechanisms are implemented"
    failure_criteria: |
      - "Critical API calls without error checking"
      - "Ignored error conditions"
      - "System continues with undefined state"
      - "No error recovery mechanisms"

  - title: "Silent Failures"
    compliance_label: true
    objective: "Ensure all error conditions are properly reported and handled"
    success_criteria: |
      - "All error conditions generate appropriate responses"
      - "Error codes are defined and documented"
      - "Failure modes are clearly identified"
      - "Error reporting mechanisms are implemented"
    failure_criteria: |
      - "Error conditions that are ignored"
      - "Missing error code definitions"
      - "Undefined failure behavior"
      - "No error reporting mechanism"

  - title: "Uncontrolled GPIO States"
    compliance_label: true
    objective: "Ensure GPIO pins are left in safe states under all conditions"
    success_criteria: |
      - "All GPIO pins have defined safe states"
      - "Cleanup code sets pins to safe states"
      - "Error paths include GPIO cleanup"
      - "Hardware safety requirements are met"
    failure_criteria: |
      - "GPIO pins left in undefined states"
      - "Missing cleanup for critical pins"
      - "No safe state definitions"
      - "Hardware safety violations"

  - title: "Missing Watchdog Handling"
    compliance_label: true
    objective: "Ensure watchdog is properly serviced to prevent system resets"
    success_criteria: |
      - "Watchdog is serviced in all long-running operations"
      - "Service intervals are within watchdog timeout"
      - "Watchdog configuration is documented"
      - "Timeout handling is implemented"
    failure_criteria: |
      - "Long operations without watchdog service"
      - "Service intervals exceed timeout"
      - "Missing watchdog configuration"
      - "No timeout handling"

  - title: "Race Conditions in Shared Memory"
    compliance_label: true
    objective: "Prevent data corruption from concurrent access to shared resources"
    success_criteria: |
      - "Shared memory access is properly synchronized"
      - "Memory barriers are used where needed"
      - "Atomic operations for critical updates"
      - "Data consistency is guaranteed"
    failure_criteria: |
      - "Unsynchronized shared memory access"
      - "Missing memory barriers"
      - "Non-atomic critical updates"
      - "Potential data corruption"

  - title: "Missing Synchronization Between PRUs"
    compliance_label: true
    objective: "Ensure proper coordination between multiple PRU cores"
    success_criteria: |
      - "Inter-PRU communication is synchronized"
      - "Shared resources have access control"
      - "Synchronization primitives are used"
      - "Coordination protocols are documented"
    failure_criteria: |
      - "Unsynchronized inter-PRU communication"
      - "Uncontrolled shared resource access"
      - "Missing synchronization primitives"
      - "Undocumented coordination"

  - title: "Missing Parameter Validation"
    compliance_label: true
    objective: "Ensure all function/macro parameters are validated"
    success_criteria: |
      - "All parameters have range validation"
      - "Invalid parameters generate compile errors"
      - "Parameter constraints are documented"
      - "Validation is comprehensive"
    failure_criteria: |
      - "Parameters without validation"
      - "Missing range checks"
      - "Undocumented parameter constraints"
      - "Incomplete validation"

  - title: "Hardcoded Magic Numbers"
    compliance_label: true
    objective: "Ensure all numeric constants are properly defined and documented"
    success_criteria: |
      - "All constants are named and defined"
      - "Magic numbers are replaced with symbolic names"
      - "Constant definitions are documented"
      - "Values are explained and justified"
    failure_criteria: |
      - "Unexplained numeric literals"
      - "Missing constant definitions"
      - "Undocumented magic numbers"
      - "Unclear value meanings"

  - title: "Contributing Requirements Drift"
    compliance_label: true
    objective: "Keep pr_compliance_checklist.yaml in sync when contribution requirements change in docs/contributing.md"
    success_criteria: |
      - "If docs/contributing.md was not modified, this check is not applicable"
      - "If docs/contributing.md was modified, pr_compliance_checklist.yaml was also modified in the same PR"
    failure_criteria: |
      - "PR modifies docs/contributing.md without a corresponding change to pr_compliance_checklist.yaml"

  - title: "AI Documentation Drift"
    compliance_label: true
    objective: "Keep docs_ai/ runbooks accurate when project structure or build patterns change"
    success_criteria: |
      - "If the PR changes project structure, file naming conventions, makefile patterns, CCS build infrastructure, adds a new device/board, or adds/removes a shared library in source/, the PR author has checked docs_ai/ and updated any runbook that no longer accurately describes the patterns"
      - "If no docs_ai/ runbook is affected, the PR description states this explicitly"
    failure_criteria: |
      - "PR adds a new project directory without confirming docs_ai/task_create_project.md still accurately describes the creation process"
      - "PR changes makefile patterns or CCS projectspec patterns used across projects without updating docs_ai/ runbooks that document those patterns"
      - "PR adds a new supported device or board without checking whether docs_ai/task_port_project.md needs updating"
      - "PR adds or removes a shared library in source/ without checking whether docs_ai/ runbooks reference that library"

  - title: "Tabs in Assembly and C Source Files"
    compliance_label: true
    objective: "Ensure assembly and C source files use spaces for indentation, not tab characters (best_practices.md §General Remarks)"
    success_criteria: |
      - "All .asm, .inc, .c, and .h source files use spaces only — no tab characters"
      - "Exempt file types: linker.cmd, makefile, makefile_projectspec, makefile_ccs_bootimage_gen, and other build infrastructure files — tab characters are acceptable in those files"
    failure_criteria: |
      - "Any .asm, .inc, .c, or .h file containing tab characters"

  - title: "Portable Assembly Include Paths"
    compliance_label: true
    objective: "Ensure assembly .include paths use PRU assembler-compatible separators (best_practices.md §Header File include rules)"
    success_criteria: |
      - 'All new or modified .asm and .inc files use the backslash character (`\`) in .include paths'
      - "Relative include paths remain valid when built on Windows or Linux hosts"
    failure_criteria: |
      - "New or modified .include paths use the forward slash character (`/`)"
      - "Include paths rely on non-PRU-assembler slash path separators"

  - title: "Bugfix: Shared Library Impact"
    compliance_label: true
    objective: "Ensure that bugfixes to shared libraries in source/ do not silently break other projects (docs/contributing.md §'Adding a bugfix')"
    success_criteria: |
      - "If the PR does not modify any file under source/, this check is not applicable"
      - "If a file in source/ was modified, the PR author has identified all projects that include or link that file and confirmed they are not broken"
    failure_criteria: |
      - "PR modifies a file in source/ without evidence that dependent projects were checked for breakage"

  - title: "Feature: README Update for Behavioral Changes"
    compliance_label: true
    objective: "Ensure the project README is updated when a feature changes user-visible behavior or hardware requirements (docs/contributing.md §'Adding a feature to an existing project')"
    success_criteria: |
      - "If the feature does not change user-visible behavior or hardware requirements, this check is not applicable"
      - "If user-visible behavior or hardware requirements changed, the project README is updated to reflect the change"
    failure_criteria: |
      - "PR adds or modifies a feature that changes user-visible behavior without updating the project README"
      - "PR adds or modifies a feature that changes hardware requirements without updating the project README"

  - title: "Port: Documentation Update Requirements"
    compliance_label: true
    objective: "Ensure documentation is updated when porting a project to a new processor or board (docs/contributing.md §'Porting a project to a new processor or board')"
    success_criteria: |
      - "If no porting to a new processor or board was performed, this check is not applicable"
      - "Project README 'Validated HW & SW' section is updated with the hardware and SDK/tool versions for the new board"
      - "Portability table in the parent section-level readme (examples/readme.md or academy/readme.md) is updated with the new board or device"
    failure_criteria: |
      - "PR adds firmware for a new board without updating the README 'Validated HW & SW' section for that board"
      - "PR adds a new device or board without updating the portability table in the parent section-level readme"

  - title: "New Project Documentation Requirements"
    compliance_label: true
    objective: "Ensure every new project directory includes complete documentation as required by docs/contributing.md"
    success_criteria: |
      - "If no new project directory was added, this check is not applicable"
      - "New project directory contains README.md"
      - "README includes an overview of what the project does"
      - "README includes a 'Supported Combinations' section"
      - "README includes a 'Validated HW & SW' section that specifies the exact hardware (including board revision) and the exact SDK and tool versions used during hardware validation"
      - "README includes project-specific steps to run the example and validate the outputs"
      - "Project is listed in the parent section-level readme (examples/readme.md or academy/readme.md) under '## Projects' with a 1–2 sentence description"
      - "Project is added to the '## Supported processors per-project' portability table with correct Y/Yport/Npru/N-hw/N-sw entries; unknown compatibility is marked with a FIXME comment"
    failure_criteria: |
      - "New project directory added without a README.md"
      - "README missing 'Validated HW & SW' section, or section does not specify SDK/tool versions or board revision"
      - "README missing project-specific steps to run and validate the example"
      - "New project not listed in the parent section-level readme or portability table"