Merge origin/main into common-code-fixes

Author: ikemilian-lewis

.gitattributes

@@ -1,3 +1,10 @@
 
 # Use bd merge for beads JSONL files
 .beads/issues.jsonl merge=beads
+
+# Enforce LF line endings for shell scripts
+*.sh text eol=lf
+
+# Legacy k8s-legacy/tools/ are shell scripts without .sh extension
+# (executed by kubelet via PATH lookup inside pods).
+k8s-legacy/tools/* text eol=lf

.github/actions/orb-cicd-app-token/action.yml

@@ -0,0 +1,57 @@
+name: 'ORB CICD App Token'
+description: 'Mint an installation token for the ORB CICD GitHub App and resolve its bot identity for git commit attribution.'
+
+inputs:
+  app-id:
+    description: 'GitHub App ID (from secrets.GH_APP_ID)'
+    required: true
+  private-key:
+    description: 'GitHub App private key (from secrets.GH_APP_PRIVATE_KEY)'
+    required: true
+
+outputs:
+  token:
+    description: 'Short-lived installation access token for the App'
+    value: ${{ steps.app-token.outputs.token }}
+  app-slug:
+    description: "App slug (e.g. open-resource-broker-cicd)"
+    value: ${{ steps.app-token.outputs.app-slug }}
+  user-id:
+    description: "Numeric user id of the App's bot account"
+    value: ${{ steps.app-user.outputs.user-id }}
+  committer-name:
+    description: 'Git committer name for App-authored commits'
+    value: ${{ steps.app-user.outputs.committer-name }}
+  committer-email:
+    description: 'Git committer email for App-authored commits'
+    value: ${{ steps.app-user.outputs.committer-email }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Mint App installation token
+      id: app-token
+      uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3
+      with:
+        app-id: ${{ inputs.app-id }}
+        private-key: ${{ inputs.private-key }}
+
+    - name: Resolve App bot identity
+      id: app-user
+      shell: bash
+      env:
+        GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
+      run: |
+        USER_ID=$(gh api "/users/${APP_SLUG}[bot]" --jq .id)
+        echo "user-id=${USER_ID}" >> "$GITHUB_OUTPUT"
+        echo "committer-name=${APP_SLUG}[bot]" >> "$GITHUB_OUTPUT"
+        echo "committer-email=${USER_ID}+${APP_SLUG}[bot]@users.noreply.github.com" >> "$GITHUB_OUTPUT"
+
+    - name: Configure git remote with App token
+      shell: bash
+      env:
+        APP_TOKEN: ${{ steps.app-token.outputs.token }}
+        REPO: ${{ github.repository }}
+      run: |
+        git remote set-url origin "https://x-access-token:${APP_TOKEN}@github.com/${REPO}.git"

.github/dependabot.yml

@@ -12,7 +12,7 @@ updates:
       - "dependencies"
       - "python"
     commit-message:
-      prefix: "chore(deps)"
+      prefix: "chore"
       include: "scope"
     open-pull-requests-limit: 3
 
@@ -97,7 +97,7 @@ updates:
       - "dependencies"
       - "go"
     commit-message:
-      prefix: "chore(deps)"
+      prefix: "chore"
       include: "scope"
     open-pull-requests-limit: 2
 
@@ -113,6 +113,6 @@ updates:
       - "dependencies"
       - "docker"
     commit-message:
-      prefix: "chore(docker)"
+      prefix: "chore"
       include: "scope"
     open-pull-requests-limit: 1

.github/workflows/cache-management.yml

@@ -34,7 +34,7 @@ jobs:
       cache-hit: ${{ steps.cache.outputs.cache-hit }}
     steps:
     - name: Checkout code
-      uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+      uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
 
     - name: Generate cache key
       id: cache-key
@@ -58,7 +58,7 @@ jobs:
 
     - name: Restore cache
       id: cache
-      uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5
+      uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v5
       with:
         path: |
           ~/.cache/uv

.github/workflows/changelog-validation.yml

@@ -20,7 +20,7 @@ jobs:
       default-python-version: ${{ steps.config.outputs.default-python-version }}
     steps:
     - name: Checkout code
-      uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+      uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
     - name: Get project configuration
       id: config
       uses: ./.github/actions/get-config
@@ -43,7 +43,7 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+      uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
       with:
         fetch-depth: 0  # Need full history for changelog generation
 

.github/workflows/ci-quality.yml

@@ -21,6 +21,27 @@ on:
       - 'uv.lock'
       - '.ruff.toml'
       - '.github/workflows/ci-quality.yml'
+  # pull_request_target is needed only for the auto-format-suggest job to call
+  # the PR Reviews API on fork PRs. All other jobs gate on event_name to avoid
+  # double execution.
+  pull_request_target:
+    branches: [ main, develop ]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - 'requirements*.txt'
+      - 'uv.lock'
+      - '.ruff.toml'
+      - '.github/workflows/ci-quality.yml'
+
+# Cancel in-progress runs when a new push arrives on the same branch/ref.
+# The auto-format job is exempted via its own job-level concurrency block
+# (cancel-in-progress: false) because it pushes a commit back to the branch —
+# cancelling it mid-push could leave the branch in a partially formatted state.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 permissions:
   contents: read
@@ -32,6 +53,8 @@ jobs:
 
   quality-check:
     name: Quality Standards
+    # Skip on pull_request_target — only auto-format-suggest needs that event.
+    if: github.event_name != 'pull_request_target'
     runs-on: ubuntu-latest
     needs: config
     permissions:
@@ -45,7 +68,7 @@ jobs:
       TESTING: ${{ needs.config.outputs.testing-flag }}
 
     steps:
-    - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
       with:
         fetch-depth: 0
 
@@ -65,6 +88,8 @@ jobs:
 
   setup-cache:
     name: Setup Cache
+    # Runs on both pull_request and pull_request_target — auto-format-suggest
+    # depends on it and needs to run on pull_request_target for fork PRs.
     needs: config
     uses: ./.github/workflows/cache-management.yml
     with:
@@ -73,18 +98,40 @@ jobs:
       python-version: ${{ needs.config.outputs.default-python-version }}
 
   auto-format:
-    name: Auto-Format Code  
-    if: github.event_name == 'pull_request'
+    name: Auto-Format Code
+    # Same-repo PRs only. Fork PRs handled by auto-format-suggest below.
+    # Bot-actor guard prevents the job re-triggering on its own push.
+    if: |
+      github.event_name == 'pull_request'
+      && github.event.pull_request.head.repo.full_name == github.repository
+      && github.actor != 'open-resource-broker-cicd[bot]'
     runs-on: ubuntu-latest
     needs: [config, setup-cache]
+    # Override the workflow-level concurrency so this job is never cancelled
+    # mid-run.  If it were interrupted after `ruff` rewrites files but before
+    # `git push`, the PR branch would be left in a half-formatted state.
+    concurrency:
+      group: ci-auto-format-${{ github.ref }}
+      cancel-in-progress: false
     permissions:
       contents: write
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
           ref: ${{ github.head_ref }}
+          # See semantic-release.yml for the rationale - the App-token URL
+          # set by the composite below must be the only credential source
+          # so the auto-format push lands as the ORB CICD App rather than
+          # falling back to github-actions[bot] via the persisted extraheader.
+          persist-credentials: false
+
+      - name: ORB CICD App token
+        id: cicd
+        uses: ./.github/actions/orb-cicd-app-token
+        with:
+          app-id: ${{ secrets.GH_APP_ID }}
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
 
       - name: Setup UV with cache
         uses: ./.github/actions/setup-uv-cached
@@ -97,26 +144,66 @@ jobs:
 
       - name: Commit formatting changes
         env:
-          GIT_AUTHOR_NAME: github-actions[bot]
-          GIT_AUTHOR_EMAIL: github-actions[bot]@users.noreply.github.com
-          GIT_COMMITTER_NAME: github-actions[bot]
-          GIT_COMMITTER_EMAIL: github-actions[bot]@users.noreply.github.com
+          GIT_AUTHOR_NAME: ${{ steps.cicd.outputs.committer-name }}
+          GIT_AUTHOR_EMAIL: ${{ steps.cicd.outputs.committer-email }}
+          GIT_COMMITTER_NAME: ${{ steps.cicd.outputs.committer-name }}
+          GIT_COMMITTER_EMAIL: ${{ steps.cicd.outputs.committer-email }}
         run: |
           git add .
           if ! git diff --staged --quiet; then
-            git commit -m "style: auto-format code with ruff [skip ci]"
+            git commit -m "style: auto-format code with ruff"
             git push
           fi
 
+  auto-format-suggest:
+    name: Auto-Format Suggestions
+    # Fork PRs: post formatted changes as PR review suggestions for the
+    # contributor to apply via the GitHub UI's "Commit suggestion" button.
+    # Uses pull_request_target so the GITHUB_TOKEN can call the PR Reviews API
+    # (POST /pulls/{id}/reviews) — pull_request fork-PR tokens cannot.
+    # The workflow file is evaluated at the base ref (safe); only the PR head
+    # code is checked out into a non-elevated working tree for formatting.
+    if: github.event_name == 'pull_request_target' && github.event.pull_request.head.repo.full_name != github.repository
+    runs-on: ubuntu-latest
+    needs: [config, setup-cache]
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout PR head
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          # No token here — formatter does not need write access; this prevents
+          # untrusted PR code from authenticating with elevated permissions.
+          persist-credentials: false
+
+      - name: Setup UV with cache
+        uses: ./.github/actions/setup-uv-cached
+        with:
+          cache-key: ${{ needs.setup-cache.outputs.cache-key }}
+          fail-on-cache-miss: false
+
+      - name: Run formatter
+        run: make format-fix
+
+      - name: Post review suggestions
+        uses: reviewdog/action-suggester@2558ba17e65a9039e73764a73009fc05fef28a46  # v1.24.3
+        with:
+          tool_name: ruff
+          level: warning
+          fail_on_error: false
+
   lint-ruff:
     name: Ruff (Code Quality)
+    if: github.event_name != 'pull_request_target'
     runs-on: ubuntu-latest
     needs: [config, setup-cache]
     permissions:
       contents: read
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
 
       - name: Setup UV with cache
         uses: ./.github/actions/setup-uv-cached
@@ -129,13 +216,14 @@ jobs:
 
   lint-ruff-optional:
     name: Ruff (Extended Checks)
+    if: github.event_name != 'pull_request_target'
     runs-on: ubuntu-latest
     needs: [config, setup-cache, lint-ruff]
     permissions:
       contents: read
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
 
       - name: Setup UV with cache
         uses: ./.github/actions/setup-uv-cached
@@ -149,13 +237,14 @@ jobs:
 
   lint-pyright:
     name: Type Checking (pyright)
+    if: github.event_name != 'pull_request_target'
     runs-on: ubuntu-latest
     needs: [config, setup-cache, lint-ruff]
     permissions:
       contents: read
     steps:
     - name: Checkout code
-      uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+      uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
 
     - name: Setup UV with cache
       uses: ./.github/actions/setup-uv-cached
@@ -169,6 +258,7 @@ jobs:
 
   arch-validation:
     name: Architecture Validation
+    if: github.event_name != 'pull_request_target'
     runs-on: ubuntu-latest
     needs: [config, setup-cache, lint-ruff]
     permissions:
@@ -187,7 +277,7 @@ jobs:
             description: "File Size Compliance"
     steps:
     - name: Checkout code
-      uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+      uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
 
     - name: Setup UV with cache
       uses: ./.github/actions/setup-uv-cached