Github Project

# .github/workflows/auto-merge-deps.yml
# Auto-merge dependency updates for repositories WITHOUT branch protection
# Use this template when: Repository has no branch protection rules
# Note: --auto flag requires branch protection; this template uses direct merge
# Note: PRs that modify workflow files require manual merge (GITHUB_TOKEN limitation)
# Merge strategy is auto-detected from repo settings (squash > merge > rebase).
name: Auto-merge dependency PRs

on:
  pull_request_target:
    types: [opened, synchronize, reopened]

permissions:
  contents: write
  pull-requests: write

jobs:
  auto-merge:
    name: Auto-merge dependency PRs
    runs-on: ubuntu-latest
    if: github.event.pull_request.user.login == 'dependabot[bot]' || github.event.pull_request.user.login == 'renovate[bot]'

    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@v2
        with:
          egress-policy: audit

      - name: Dependabot metadata
        id: metadata
        if: github.event.pull_request.user.login == 'dependabot[bot]'
        uses: dependabot/fetch-metadata@v2
        with:
          github-token: "${{ secrets.GITHUB_TOKEN }}"

      - name: Auto-approve PR
        run: gh pr review --approve "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Wait for CI checks
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          echo "Waiting for CI checks to pass..."
          sleep 30
          # Poll checks excluding this workflow to avoid deadlock
          for i in $(seq 1 90); do
            CHECKS=$(gh pr checks "$PR_URL" --json name,state,conclusion 2>/dev/null || echo "[]")
            # Filter out auto-merge workflow and check states
            PENDING=$(echo "$CHECKS" | jq -r '.[] | select(.name != "Auto-merge dependency PRs" and .name != "auto-merge") | select(.state == "PENDING" or .conclusion == null) | .name' | head -5)
            FAILED=$(echo "$CHECKS" | jq -r '.[] | select(.name != "Auto-merge dependency PRs" and .name != "auto-merge") | select(.conclusion == "FAILURE" or .conclusion == "CANCELLED") | .name' | head -5)

            if [ -n "$FAILED" ]; then
              echo "CI checks failed: $FAILED"
              exit 1
            fi

            if [ -z "$PENDING" ]; then
              echo "All CI checks passed!"
              exit 0
            fi

            echo "Waiting for: $PENDING"
            sleep 10
          done
          echo "Timeout waiting for CI checks"
          exit 1

      - name: Check for workflow file changes
        id: check-workflows
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          WORKFLOW_FILES=$(gh pr diff "$PR_URL" --name-only | grep -E '^\.github/workflows/' || true)
          if [ -n "$WORKFLOW_FILES" ]; then
            echo "modifies_workflows=true" >> "$GITHUB_OUTPUT"
            echo "⚠️ PR modifies workflow files - requires manual merge (GITHUB_TOKEN lacks workflows permission)"
            echo "Modified workflow files:"
            echo "$WORKFLOW_FILES"
          else
            echo "modifies_workflows=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Merge PR
        if: steps.check-workflows.outputs.modifies_workflows != 'true'
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # Detect allowed merge strategy
          # Prefer squash (works with signed commit requirements, clean for single-commit PRs)
          # then merge (also works with signed commits), then rebase (cannot be auto-signed)
          STRATEGY=$(gh api "repos/${{ github.repository }}" --jq '
            if .allow_squash_merge then "--squash"
            elif .allow_merge_commit then "--merge"
            elif .allow_rebase_merge then "--rebase"
            else "--squash" end')
          echo "Using merge strategy: $STRATEGY"
          gh pr merge $STRATEGY "$PR_URL"

      - name: Comment on workflow PR
        if: steps.check-workflows.outputs.modifies_workflows == 'true'
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr comment "$PR_URL" --body "✅ CI checks passed and PR approved. This PR modifies workflow files and requires manual merge (GITHUB_TOKEN cannot merge workflow changes)."

# .github/workflows/auto-merge-deps.yml
# Auto-merge dependency updates for repositories with MERGE QUEUE enabled
# Use this template when: Repository has merge queue configured
# Note: mergeMethod is NOT a valid parameter for enqueuePullRequest - merge method is set by queue config
name: Auto-merge dependency PRs

on:
  pull_request_target:
    types: [opened, synchronize, reopened]

permissions:
  contents: write
  pull-requests: write

jobs:
  auto-merge:
    name: Auto-merge dependency PRs
    runs-on: ubuntu-latest
    # Use github.event.pull_request.user.login instead of github.actor
    # because actor can change on synchronize/rerun events
    if: >-
      github.event.pull_request.user.login == 'dependabot[bot]' ||
      github.event.pull_request.user.login == 'renovate[bot]'

    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@v2
        with:
          egress-policy: audit

      - name: Dependabot metadata
        id: metadata
        if: github.event.pull_request.user.login == 'dependabot[bot]'
        uses: dependabot/fetch-metadata@v2
        with:
          github-token: "${{ secrets.GITHUB_TOKEN }}"

      - name: Auto-approve PR
        run: gh pr review --approve "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Wait for required status checks
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          echo "Waiting for all required status checks to pass..."
          # Wait up to 30 minutes for checks to complete
          timeout 1800 gh pr checks "$PR_URL" --watch --fail-fast || {
            echo "Status checks did not pass within timeout"
            exit 1
          }
          echo "All status checks passed!"

      - name: Add to merge queue
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NODE_ID: ${{ github.event.pull_request.node_id }}
        run: |
          gh api graphql -f query='
            mutation($pullRequestId: ID!) {
              enqueuePullRequest(input: {pullRequestId: $pullRequestId}) {
                mergeQueueEntry { id }
              }
            }' -f pullRequestId="$PR_NODE_ID" || {
              echo "Failed to enqueue PR in merge queue"
              exit 1
            }
          echo "PR successfully added to merge queue!"

# .github/workflows/auto-merge-deps.yml
# Auto-merge dependency updates from Dependabot and Renovate
# Requires: branch protection enabled (--auto flag needs it)
# Merge strategy is auto-detected from repo settings (squash > merge > rebase)
name: Auto-merge dependency PRs

on:
  pull_request_target:
    types: [opened, synchronize, reopened]

permissions:
  contents: read

jobs:
  auto-merge:
    name: Auto-merge dependency PRs
    runs-on: ubuntu-latest
    # Use github.event.pull_request.user.login instead of github.actor
    # because actor can change on synchronize/rerun events
    if: >-
      github.event.pull_request.user.login == 'dependabot[bot]' ||
      github.event.pull_request.user.login == 'renovate[bot]'

    permissions:
      contents: write
      pull-requests: write

    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@v2
        with:
          egress-policy: audit

      - name: Approve PR
        run: gh pr review --approve "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Enable auto-merge
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # Detect allowed merge strategy
          # Prefer squash (works with signed commit requirements, clean for single-commit PRs)
          # then merge (also works with signed commits), then rebase (cannot be auto-signed)
          STRATEGY=$(gh api "repos/${{ github.repository }}" --jq '
            if .allow_squash_merge then "--squash"
            elif .allow_merge_commit then "--merge"
            elif .allow_rebase_merge then "--rebase"
            else "--squash" end')
          echo "Using merge strategy: $STRATEGY"
          gh pr merge --auto $STRATEGY "$PR_URL"

{
  "required_status_checks": null,
  "enforce_admins": false,
  "required_pull_request_reviews": {
    "required_approving_review_count": 1,
    "dismiss_stale_reviews": false,
    "require_code_owner_reviews": false,
    "require_last_push_approval": false
  },
  "restrictions": null,
  "required_linear_history": false,
  "allow_force_pushes": false,
  "allow_deletions": false,
  "required_conversation_resolution": true,
  "lock_branch": false,
  "allow_fork_syncing": false
}

---
name: Bug Report
about: Report a bug to help us improve
title: '[BUG] '
labels: bug
assignees: ''
---

## Description

A clear and concise description of the bug.

## Steps to Reproduce

1. ...
2. ...
3. ...

## Expected Behavior

What you expected to happen.

## Actual Behavior

What actually happened.

## Environment

- **Version**:
- **OS**:
- **Go/PHP/Node version**:
- **Other relevant info**:

## Logs / Error Messages

```
Paste any relevant logs or error messages here
```

## Screenshots

If applicable, add screenshots to help explain the problem.

## Additional Context

Any other relevant information about the problem.

## Possible Solution

If you have suggestions for fixing the bug, describe them here.

# .github/CODEOWNERS
# Code ownership for automatic review assignment
# Documentation: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners

# Default owners for everything in the repo
* @{{ORG}}/maintainers

# Core source code requires team review
/src/ @{{ORG}}/core-team
/Classes/ @{{ORG}}/core-team
/internal/ @{{ORG}}/core-team
/pkg/ @{{ORG}}/core-team

# CI/CD and security-sensitive files require maintainer approval
/.github/ @{{ORG}}/maintainers
/.github/workflows/ @{{ORG}}/security-team

# Security policy requires security team approval
/SECURITY.md @{{ORG}}/security-team

# Documentation can be reviewed by docs team
/docs/ @{{ORG}}/docs-team
/Documentation/ @{{ORG}}/docs-team
*.md @{{ORG}}/docs-team

# Tests can be reviewed by QA team
/tests/ @{{ORG}}/qa-team
/Tests/ @{{ORG}}/qa-team
*_test.go @{{ORG}}/qa-team
*Test.php @{{ORG}}/qa-team

# Contributing to {{PROJECT}}

Thank you for your interest in contributing! This document provides guidelines and information for contributors.

## Code of Conduct

This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). By participating, you agree to uphold this code.

## Getting Started

### Prerequisites

- {{LANGUAGE}} {{VERSION}}+
- Git

### Development Setup

```bash
# Clone the repository
git clone https://github.com/{{ORG}}/{{REPO}}.git
cd {{REPO}}

# Install dependencies
{{INSTALL_COMMAND}}

# Run tests
{{TEST_COMMAND}}
```

## How to Contribute

### Reporting Bugs

1. Check existing [issues](https://github.com/{{ORG}}/{{REPO}}/issues) first
2. Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md)
3. Include:
   - Clear description of the problem
   - Steps to reproduce
   - Expected vs actual behavior
   - Version information

### Suggesting Features

1. Check existing [feature requests](https://github.com/{{ORG}}/{{REPO}}/issues?q=label:enhancement)
2. Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md)
3. Describe the use case and proposed solution

### Submitting Code

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Make your changes
4. Write/update tests
5. Ensure all tests pass: `{{TEST_COMMAND}}`
6. Commit using [Conventional Commits](#commit-messages)
7. Push and create a Pull Request

## Development Guidelines

### Code Style

{{CODE_STYLE_INSTRUCTIONS}}

Run code formatting before committing:
```bash
{{FORMAT_COMMAND}}
```

### Testing

We use a multi-layer testing strategy:

- **Unit Tests**: Test individual functions/methods
- **Integration Tests**: Test component interactions
- **End-to-End Tests**: Test complete workflows

Run all tests:
```bash
{{TEST_COMMAND}}
```

### Commit Messages

We follow [Conventional Commits](https://www.conventionalcommits.org/):

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Code style (formatting, no logic change)
- `refactor`: Code refactoring
- `perf`: Performance improvements
- `test`: Adding/updating tests
- `build`: Build system changes
- `ci`: CI configuration changes
- `chore`: Maintenance tasks

**Examples:**
```
feat: add user authentication
fix(api): resolve timeout on large requests
docs: update installation instructions
```

### Pull Request Process

1. Update documentation if needed
2. Add tests for new functionality
3. Ensure CI passes
4. Request review from maintainers
5. Address review feedback
6. Squash commits if requested

### Pull Request Checklist

- [ ] Code follows project style guidelines
- [ ] Tests added/updated and passing
- [ ] Documentation updated
- [ ] Commit messages follow Conventional Commits
- [ ] No unrelated changes included

## Release Process

Releases are automated via GitHub Actions when tags are pushed:

```bash
git tag v1.0.0
git push origin v1.0.0
```

## Getting Help

- Open a [GitHub Discussion](https://github.com/{{ORG}}/{{REPO}}/discussions)
- Check existing documentation
- Review closed issues for similar problems

## License

By contributing, you agree that your contributions will be licensed under the project's [license](LICENSE).

# .github/dependabot.yml
# Automated dependency updates
# Documentation: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates

version: 2
updates:
  # {{ECOSYSTEM}} dependencies
  - package-ecosystem: "{{ECOSYSTEM}}"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
      time: "06:00"
      timezone: "Europe/Berlin"
    groups:
      dependencies:
        patterns:
          - "*"
    commit-message:
      prefix: "deps"
    labels:
      - "dependencies"
    open-pull-requests-limit: 10

  # GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
      time: "06:00"
      timezone: "Europe/Berlin"
    groups:
      github-actions:
        patterns:
          - "*"
    commit-message:
      prefix: "ci"
    labels:
      - "dependencies"
      - "github-actions"

  # Docker (if applicable)
  # - package-ecosystem: "docker"
  #   directory: "/"
  #   schedule:
  #     interval: "weekly"
  #   commit-message:
  #     prefix: "docker"
  #   labels:
  #     - "dependencies"
  #     - "docker"

---
name: Feature Request
about: Suggest an enhancement or new feature
title: '[FEATURE] '
labels: enhancement
assignees: ''
---

## Problem Statement

A clear description of the problem or limitation you're experiencing.

**Is this related to an existing issue?**
Link to any related issues.

## Proposed Solution

Describe the feature or enhancement you'd like to see.

### Implementation Ideas

If you have thoughts on how this could be implemented, share them here.

## Alternatives Considered

Describe any alternative solutions or workarounds you've considered.

## Use Case

Describe the use case for this feature. Who would benefit and how?

**Example scenario:**
```
As a [type of user], I want to [do something] so that [benefit].
```

## Additional Context

- Screenshots, mockups, or examples from other projects
- Links to relevant documentation or discussions
- Any other context that helps explain the request

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Priority

How important is this feature to you?
- [ ] Critical - blocking my work
- [ ] High - would significantly improve my workflow
- [ ] Medium - nice to have
- [ ] Low - minor improvement

# .github/workflows/pr-quality.yml
# Solo-maintainer auto-approve: approves PRs from repo collaborators
# so that required_approving_review_count >= 1 is satisfied without
# manual review for trusted authors.
#
# SECURITY: This workflow uses pull_request_target which runs with base branch
# permissions. NEVER add an actions/checkout step here -- that would allow code
# from the PR to execute with write access to the repository.
#
# Bootstrap: The PR that introduces this workflow must be approved manually
# (the workflow isn't on the base branch yet). All subsequent PRs auto-approve.

name: PR Quality Gates

on:
    pull_request_target:
        types: [opened, synchronize, reopened]

jobs:
    auto-approve:
        name: Auto-approve (collaborators)
        runs-on: ubuntu-latest
        permissions:
            pull-requests: write

        steps:
            - name: Harden Runner
              uses: step-security/harden-runner@v2
              with:
                  egress-policy: audit

            - name: Check author permission
              id: check-permission
              env:
                  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
                  PR_AUTHOR: ${{ github.event.pull_request.user.login }}
                  REPO: ${{ github.repository }}
              run: |
                  PERMISSION=$(gh api "repos/$REPO/collaborators/$PR_AUTHOR/permission" --jq '.permission' 2>/dev/null || echo "none")
                  echo "permission=$PERMISSION" >> "$GITHUB_OUTPUT"

            - name: Auto-approve PR
              if: steps.check-permission.outputs.permission == 'admin' || steps.check-permission.outputs.permission == 'write'
              env:
                  PR_URL: ${{ github.event.pull_request.html_url }}
                  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
              run: gh pr review --approve "$PR_URL"

## Description

Brief description of the changes in this PR.

## Type of Change

- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to change)
- [ ] Documentation update
- [ ] Refactoring (no functional changes)
- [ ] Performance improvement
- [ ] Test update

## Related Issues

Fixes #(issue number)

Related to #(issue number)

## Changes Made

- Change 1
- Change 2
- Change 3

## Testing

### How to Test

1. Step 1
2. Step 2
3. Step 3

### Test Results

- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist

- [ ] My code follows the project's coding standards
- [ ] I have run linting/formatting and all checks pass
- [ ] I have added tests covering my changes
- [ ] I have updated documentation as needed
- [ ] My commits follow the conventional commit format
- [ ] I have rebased on the latest main branch
- [ ] Breaking changes are documented

## Screenshots (if applicable)

| Before | After |
|--------|-------|
|        |       |

## Additional Notes

Any additional information reviewers should know.

## Deployment Notes

Any special considerations for deploying this change.

# Release Labeler Workflow
# Automatically labels PRs and issues with the release version they shipped in
# and creates an announcement discussion for each release.
#
# Features:
# - Creates a discussion in Announcements category for each release
# - Creates `released:vX.Y.Z` label on release publish
# - Labels all PRs merged between previous and current release
# - Labels issues that were closed by those PRs
# - Adds comment linking to the release
#
# Usage:
# 1. Copy to .github/workflows/release-labeler.yml
# 2. Ensure GITHUB_TOKEN has issues:write, pull-requests:write, and discussions:write permissions
# 3. Enable Discussions on the repository (Settings > General > Features > Discussions)

name: Release Labeler

on:
  release:
    types: [published]

permissions:
  contents: read

jobs:
  announce-release:
    name: Create Discussion Announcement
    runs-on: ubuntu-latest

    permissions:
      contents: read
      discussions: write

    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

      - name: Resolve announcements category ID
        id: category
        env:
          GH_TOKEN: ${{ github.token }}
          REPO_OWNER: ${{ github.repository_owner }}
          REPO_NAME: ${{ github.event.repository.name }}
        run: |
          CATEGORY_ID=$(gh api graphql -f query='
            query($owner: String!, $name: String!) {
              repository(owner: $owner, name: $name) {
                discussionCategories(first: 20) {
                  nodes { id name }
                }
              }
            }' -f owner="$REPO_OWNER" -f name="$REPO_NAME" \
            --jq '.data.repository.discussionCategories.nodes[] | select(.name == "Announcements") | .id')

          if [[ -z "$CATEGORY_ID" ]]; then
            echo "::warning::No 'Announcements' discussion category found, skipping"
            echo "found=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          echo "id=$CATEGORY_ID" >> "$GITHUB_OUTPUT"
          echo "found=true" >> "$GITHUB_OUTPUT"

      - name: Create announcement discussion
        if: steps.category.outputs.found == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
          REPO_OWNER: ${{ github.repository_owner }}
          REPO_NAME: ${{ github.event.repository.name }}
          RELEASE_TAG: ${{ github.event.release.tag_name }}
          RELEASE_URL: ${{ github.event.release.html_url }}
          RELEASE_BODY: ${{ github.event.release.body }}
          REPO_ID: ${{ github.event.repository.node_id }}
          CATEGORY_ID: ${{ steps.category.outputs.id }}
        run: |
          # Build discussion body safely (no shell expansion of release body)
          {
            printf '## [%s](%s)\n\n' "$RELEASE_TAG" "$RELEASE_URL"
            printf '%s\n\n' "$RELEASE_BODY"
            printf '---\n*Automatically created from [GitHub Release](%s).*\n' "$RELEASE_URL"
          } > /tmp/discussion-body.md

          # Check if discussion already exists (search all announcements by title)
          EXISTING=$(gh api graphql -f query='
            query($owner: String!, $name: String!, $categoryId: ID!) {
              repository(owner: $owner, name: $name) {
                discussions(first: 100, categoryId: $categoryId, orderBy: {field: CREATED_AT, direction: DESC}) {
                  nodes { title }
                }
              }
            }' \
            -f owner="$REPO_OWNER" \
            -f name="$REPO_NAME" \
            -f categoryId="$CATEGORY_ID" \
            --jq '.data.repository.discussions.nodes[].title' | grep -Fx -- "$RELEASE_TAG" || true)

          if [[ -n "$EXISTING" ]]; then
            echo "Discussion for $RELEASE_TAG already exists, skipping"
            exit 0
          fi

          gh api graphql \
            -f query='mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
              createDiscussion(input: {repositoryId: $repoId, categoryId: $categoryId, title: $title, body: $body}) {
                discussion { url }
              }
            }' \
            -f repoId="$REPO_ID" \
            -f categoryId="$CATEGORY_ID" \
            -f title="$RELEASE_TAG" \
            -F body=@/tmp/discussion-body.md

          echo "## Announcement Created" >> $GITHUB_STEP_SUMMARY
          echo "Discussion created for $RELEASE_TAG" >> $GITHUB_STEP_SUMMARY

  label-release:
    name: Label PRs and Issues
    runs-on: ubuntu-latest

    permissions:
      contents: read
      issues: write
      pull-requests: write

    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

      - name: Get release info
        id: release
        env:
          RELEASE_TAG: ${{ github.event.release.tag_name }}
          RELEASE_URL: ${{ github.event.release.html_url }}
        run: |
          echo "tag=${RELEASE_TAG}" >> $GITHUB_OUTPUT
          echo "url=${RELEASE_URL}" >> $GITHUB_OUTPUT
          # Label format: released:v1.2.3
          echo "label=released:${RELEASE_TAG}" >> $GITHUB_OUTPUT

      - name: Get previous release tag
        id: prev_release
        env:
          GH_TOKEN: ${{ github.token }}
          CURRENT_TAG: ${{ steps.release.outputs.tag }}
        run: |
          # Get the previous release tag (skip current)
          PREV_TAG=$(gh api repos/${{ github.repository }}/releases \
            --jq "[.[] | select(.tag_name != \"${CURRENT_TAG}\" and .prerelease == false)] | .[0].tag_name // \"\"")
          echo "tag=${PREV_TAG}" >> $GITHUB_OUTPUT
          echo "Previous release: ${PREV_TAG:-none}"

      - name: Create release label
        env:
          GH_TOKEN: ${{ github.token }}
          LABEL_NAME: ${{ steps.release.outputs.label }}
          RELEASE_TAG: ${{ steps.release.outputs.tag }}
        run: |
          # Create or update label (green color: 0e8a16)
          gh label create "${LABEL_NAME}" \
            --repo ${{ github.repository }} \
            --color 0e8a16 \
            --description "Released in ${RELEASE_TAG}" \
            --force

      - name: Find and label merged PRs
        id: label_prs
        env:
          GH_TOKEN: ${{ github.token }}
          LABEL_NAME: ${{ steps.release.outputs.label }}
          RELEASE_URL: ${{ steps.release.outputs.url }}
          RELEASE_TAG: ${{ steps.release.outputs.tag }}
          PREV_TAG: ${{ steps.prev_release.outputs.tag }}
        run: |
          LABELED_PRS=""

          # Get merge commits between tags
          if [[ -n "${PREV_TAG}" ]]; then
            echo "Finding PRs merged between ${PREV_TAG} and ${RELEASE_TAG}"
            # Get commits between tags with explicit error handling
            if ! COMMITS=$(gh api repos/${{ github.repository }}/compare/${PREV_TAG}...${RELEASE_TAG} \
              --jq '.commits[].sha' 2>&1); then
              echo "::warning::Failed to fetch commits between ${PREV_TAG} and ${RELEASE_TAG}: ${COMMITS}"
              COMMITS=""
            fi
          else
            echo "No previous release found"
            COMMITS=""
          fi

          # Find merged PRs
          if [[ -n "${COMMITS}" ]]; then
            # Search for PRs by merge commit
            for sha in ${COMMITS}; do
              PR_NUM=$(gh api repos/${{ github.repository }}/commits/${sha}/pulls \
                --jq '.[0].number // empty' 2>/dev/null || echo "")
              if [[ -n "${PR_NUM}" ]]; then
                echo "Found PR #${PR_NUM} for commit ${sha:0:7}"
                LABELED_PRS="${LABELED_PRS} ${PR_NUM}"
                # Add label
                gh pr edit ${PR_NUM} --repo ${{ github.repository }} \
                  --add-label "${LABEL_NAME}" 2>/dev/null || true
                # Add comment (skip if already commented)
                EXISTING=$(gh pr view ${PR_NUM} --repo ${{ github.repository }} \
                  --json comments --jq ".comments[].body | select(contains(\"${RELEASE_TAG}\"))" 2>/dev/null || echo "")
                if [[ -z "${EXISTING}" ]]; then
                  gh pr comment ${PR_NUM} --repo ${{ github.repository }} \
                    --body "Released in [${RELEASE_TAG}](${RELEASE_URL})" 2>/dev/null || true
                fi
              fi
            done
          else
            # Fallback for first release: find PRs merged to default branch
            # Only label PRs that don't already have a released: label
            echo "Using fallback: searching recently merged PRs without release labels"
            PR_LIST=$(gh pr list --repo ${{ github.repository }} --state merged --limit 50 \
              --json number,labels --jq '.[] | select(.labels | map(.name) | any(startswith("released:")) | not) | .number')
            for PR_NUM in ${PR_LIST}; do
              echo "Labeling PR #${PR_NUM} (first release)"
              LABELED_PRS="${LABELED_PRS} ${PR_NUM}"
              gh pr edit ${PR_NUM} --repo ${{ github.repository }} \
                --add-label "${LABEL_NAME}" 2>/dev/null || true
            done
          fi

          # Output labeled PRs for next step (avoid race condition with label query)
          echo "labeled_prs=${LABELED_PRS}" >> $GITHUB_OUTPUT

      - name: Find and label closed issues
        env:
          GH_TOKEN: ${{ github.token }}
          LABEL_NAME: ${{ steps.release.outputs.label }}
          RELEASE_URL: ${{ steps.release.outputs.url }}
          RELEASE_TAG: ${{ steps.release.outputs.tag }}
          LABELED_PRS: ${{ steps.label_prs.outputs.labeled_prs }}
        run: |
          # Use PR numbers from previous step (avoids race condition with label propagation)
          for PR_NUM in ${LABELED_PRS}; do
            # Get issues linked/closed by this PR
            LINKED_ISSUES=$(gh pr view ${PR_NUM} --repo ${{ github.repository }} \
              --json closingIssuesReferences --jq '.closingIssuesReferences[].number' 2>/dev/null || echo "")

            for ISSUE_NUM in ${LINKED_ISSUES}; do
              echo "Labeling issue #${ISSUE_NUM} (closed by PR #${PR_NUM})"
              gh issue edit ${ISSUE_NUM} --repo ${{ github.repository }} \
                --add-label "${LABEL_NAME}" 2>/dev/null || true
              # Add comment
              EXISTING=$(gh issue view ${ISSUE_NUM} --repo ${{ github.repository }} \
                --json comments --jq ".comments[].body | select(contains(\"${RELEASE_TAG}\"))" 2>/dev/null || echo "")
              if [[ -z "${EXISTING}" ]]; then
                gh issue comment ${ISSUE_NUM} --repo ${{ github.repository }} \
                  --body "Fixed in [${RELEASE_TAG}](${RELEASE_URL})" 2>/dev/null || true
              fi
            done
          done

      - name: Summary
        env:
          GH_TOKEN: ${{ github.token }}
          LABEL_NAME: ${{ steps.release.outputs.label }}
        run: |
          PR_COUNT=$(gh pr list --repo ${{ github.repository }} --state merged \
            --label "${LABEL_NAME}" --json number --jq 'length')
          ISSUE_COUNT=$(gh issue list --repo ${{ github.repository }} --state closed \
            --label "${LABEL_NAME}" --json number --jq 'length')
          # Properly URL-encode the query parameter
          QUERY="label:${LABEL_NAME}"
          ENCODED_QUERY=$(printf '%s' "${QUERY}" | jq -sRr @uri)
          echo "## Release Labeling Complete" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "- **Label:** \`${LABEL_NAME}\`" >> $GITHUB_STEP_SUMMARY
          echo "- **PRs labeled:** ${PR_COUNT}" >> $GITHUB_STEP_SUMMARY
          echo "- **Issues labeled:** ${ISSUE_COUNT}" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "[View all labeled items](https://github.com/${{ github.repository }}/issues?q=${ENCODED_QUERY})" >> $GITHUB_STEP_SUMMARY

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended",
    ":semanticCommits",
    ":semanticCommitTypeAll(chore)",
    "group:allNonMajor"
  ],
  "labels": ["dependencies"],
  "prHourlyLimit": 2,
  "prConcurrentLimit": 5,
  "timezone": "Europe/Berlin",
  "schedule": ["before 7am on monday"],
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    },
    {
      "matchManagers": ["github-actions"],
      "groupName": "GitHub Actions",
      "automerge": true
    },
    {
      "matchDepTypes": ["devDependencies"],
      "automerge": true
    }
  ]
}

# Security Policy

## Supported Versions

| Version | Supported          |
| ------- | ------------------ |
| latest  | :white_check_mark: |
| < latest | :x:               |

## Reporting a Vulnerability

1. **Do NOT open a public GitHub issue** for security vulnerabilities
2. Report via [GitHub Security Advisories](https://github.com/{{ORG}}/{{REPO}}/security/advisories/new)
3. Or email: {{SECURITY_EMAIL}}

### What to Include

- Description of the vulnerability
- Steps to reproduce
- Potential impact
- Suggested fix (if any)

### Response Timeline

- **Initial response**: Within 48 hours
- **Status update**: Within 7 days
- **Resolution target**: Within 30 days

## Security Measures

This project implements:

- **SLSA Level 3** provenance for releases
- **Signed checksums** using Sigstore/Cosign
- **SBOM generation** for all releases
- **CodeQL** static analysis
- **Dependency scanning** via Dependabot

## Supply Chain Security

### Verifying Releases

#### Using GitHub Attestations (Recommended)
```bash
# Download release archive
gh release download v1.0.0 --pattern '*.tar.gz'

# Verify provenance via GitHub's built-in attestation
gh attestation verify {{BINARY}}.tar.gz --repo {{ORG}}/{{REPO}}
```

#### Using slsa-verifier (Legacy)
```bash
# Download release assets
gh release download v1.0.0 --pattern '*.tar.gz'
gh release download v1.0.0 --pattern '*.intoto.jsonl'

# Verify with slsa-verifier
slsa-verifier verify-artifact \
  --provenance-path {{BINARY}}.intoto.jsonl \
  --source-uri github.com/{{ORG}}/{{REPO}} \
  {{BINARY}}.tar.gz
```

#### Checksum Verification
```bash
# Download checksum files
gh release download v1.0.0 --pattern 'checksums.txt*'

# Verify signature
cosign verify-blob \
  --certificate checksums.txt.pem \
  --signature checksums.txt.sig \
  checksums.txt

# Verify checksums
sha256sum -c checksums.txt
```

## Branch Protection

The `main` branch requires:

- Pull request with 1+ approvals
- Passing CI status checks
- Up-to-date with base branch
- No force pushes

## OpenSSF Scorecard

This project is monitored by OpenSSF Scorecard:

[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/{{ORG}}/{{REPO}}/badge)](https://securityscorecards.dev/viewer/?uri=github.com/{{ORG}}/{{REPO}})

# Example checkpoints.yaml for github-project skill
# Copy this to your skill repo root as checkpoints.yaml

version: 1
skill_id: github-project

mechanical:
  # === FILE EXISTENCE CHECKS ===
  - id: GH-01
    type: file_exists
    target: README.md
    severity: error
    desc: "README.md must exist"

  # Brace expansion covers SPDX-style split-license filenames common in
  # multi-licence skill repos plus the GNU COPYING convention. Single line
  # because the runner's YAML parser doesn't unfold `>-` folded scalars
  # for `target:` fields (it's bash regex, not a real YAML parser).
  - id: GH-02
    type: file_exists
    target: "{LICENSE,LICENSE.md,LICENSE.txt,COPYING,COPYING.md,COPYING.txt,LICENSE-MIT,LICENSE-APACHE,LICENSE-APACHE-2.0,LICENSE-BSD,LICENSE-BSD-2-Clause,LICENSE-BSD-3-Clause,LICENSE-CC-BY-SA-4.0,LICENSE-CC0-1.0,LICENSE-GPL,LICENSE-GPL-2.0,LICENSE-GPL-3.0,LICENSE-LGPL,LICENSE-LGPL-3.0,LICENSE-AGPL,LICENSE-AGPL-3.0,LICENSE-MPL,LICENSE-MPL-2.0}"
    severity: error
    desc: >-
      LICENSE file must exist. Accepts split-license naming (LICENSE-MIT,
      LICENSE-CC-BY-SA-4.0, etc.) and the GNU COPYING convention.

  - id: GH-03
    type: file_exists
    target: "{SECURITY.md,.github/SECURITY.md,docs/SECURITY.md}"
    org_provides: SECURITY.md
    severity: info
    desc: "SECURITY.md should exist for vulnerability reporting. Satisfied org-wide via {owner}/.github/SECURITY.md when present."

  - id: GH-04
    type: file_exists
    target: "{CONTRIBUTING.md,.github/CONTRIBUTING.md,docs/CONTRIBUTING.md}"
    org_provides: CONTRIBUTING.md
    severity: info
    desc: "CONTRIBUTING.md should exist. Satisfied org-wide via {owner}/.github/CONTRIBUTING.md when present."

  - id: GH-05
    type: file_exists
    target: "{.github/CODEOWNERS,CODEOWNERS,docs/CODEOWNERS}"
    severity: warning
    desc: >-
      CODEOWNERS must exist in the repository itself for GitHub to assign
      reviewers (only `.github/`, root, or `docs/` on the default branch are
      recognised). Org-wide `.github` does NOT satisfy CODEOWNERS — that
      mechanism only provides templates and community-health files, not
      review-routing rules.

  - id: GH-06
    type: file_exists
    target: "{.github/dependabot.yml,.github/dependabot.yaml,renovate.json,renovate.json5,.github/renovate.json,.github/renovate.json5,.renovaterc.json,.renovaterc.json5,.renovaterc}"
    severity: warning
    desc: >-
      Dependency update automation should be configured (Dependabot or
      Renovate). Accepts both .yml/.yaml for Dependabot and .json/.json5
      for Renovate.

  - id: GH-07
    type: file_exists
    target: "{.github/PULL_REQUEST_TEMPLATE.md,.github/pull_request_template.md,PULL_REQUEST_TEMPLATE.md,pull_request_template.md,docs/PULL_REQUEST_TEMPLATE.md,docs/pull_request_template.md}"
    org_provides: "{PULL_REQUEST_TEMPLATE.md,pull_request_template.md}"
    severity: info
    desc: "PR template should exist (also accepted in docs/). Satisfied org-wide via {owner}/.github/PULL_REQUEST_TEMPLATE.md or pull_request_template.md when present."

  # Issue templates: prefer the modern `.yml` form templates (structured
  # fields, validation, required inputs) over legacy `.md` files. Accept
  # either, but `.yml` is the recommended Netresearch standard.
  - id: GH-08
    type: file_exists
    target: "{.github/ISSUE_TEMPLATE/bug_report.yml,.github/ISSUE_TEMPLATE/bug_report.md}"
    org_provides: "{ISSUE_TEMPLATE/bug_report.yml,ISSUE_TEMPLATE/bug_report.md}"
    severity: info
    desc: "Bug report template should exist (prefer .yml form template). Satisfied org-wide via {owner}/.github/ISSUE_TEMPLATE/bug_report.yml or .md when present."

  - id: GH-09
    type: file_exists
    target: "{.github/ISSUE_TEMPLATE/feature_request.yml,.github/ISSUE_TEMPLATE/feature_request.md}"
    org_provides: "{ISSUE_TEMPLATE/feature_request.yml,ISSUE_TEMPLATE/feature_request.md}"
    severity: info
    desc: "Feature request template should exist (prefer .yml form template). Satisfied org-wide via {owner}/.github/ISSUE_TEMPLATE/feature_request.yml or .md when present."

  # === CONTENT CHECKS ===
  - id: GH-10
    type: contains
    target: README.md
    pattern: "codecov.io"
    severity: warning
    desc: "README should have Codecov badge"

  - id: GH-11
    type: regex
    target: README.md
    pattern: "github.com/.*/actions/workflows"
    severity: error
    desc: "README should have CI status badge"

  - id: GH-12
    type: regex
    target: README.md
    pattern: "img.shields.io.*license"
    severity: warning
    desc: "README should have license badge"

  # === DEPENDABOT CHECKS ===
  - id: GH-13
    type: regex
    target: "{.github/dependabot.yml,.github/dependabot.yaml}"
    pattern: 'package-ecosystem:\s*"?(composer|gomod|npm|pip)"?'
    severity: warning
    desc: "Dependabot should monitor language-specific dependencies (composer, gomod, npm, pip)"

  - id: GH-14
    type: regex
    target: "{.github/dependabot.yml,.github/dependabot.yaml}"
    pattern: 'package-ecosystem:\s*"?github-actions"?'
    severity: warning
    desc: "Dependabot should monitor GitHub Actions"

  # === GITIGNORE ===
  - id: GH-17
    type: file_exists
    target: .gitignore
    severity: error
    desc: ".gitignore must exist"

  # === RENOVATE (alternative to Dependabot) ===
  - id: GH-18
    type: file_exists
    target: renovate.json
    severity: info
    desc: "Renovate config may exist as alternative to Dependabot"

  # === SECURITY CONFIG ===
  # CodeQL / Scorecard can be a dedicated workflow file OR a job in another
  # workflow that delegates to the netresearch reusable workflow. Same
  # pattern as ER-19/20 in enterprise-readiness-skill PR #55.
  - id: GH-19
    type: regex
    target: ".github/workflows/*.{yml,yaml}"
    pattern: 'uses:[[:space:]]*github/codeql-action|uses:[[:space:]]*netresearch/[.]github/[.]github/workflows/codeql[.]yml'
    follow_uses: true
    severity: warning
    desc: >-
      CodeQL must be wired up. Satisfied by either a local workflow that uses
      github/codeql-action directly, or a job that delegates to a reusable
      workflow (e.g. netresearch/.github/.github/workflows/codeql.yml) whose
      upstream body uses github/codeql-action. follow_uses: true expands the
      search to fetch the reusable workflow contents one hop via gh api.

  - id: GH-20
    type: regex
    target: ".github/workflows/*.{yml,yaml}"
    pattern: 'uses:[[:space:]]*ossf/scorecard-action|uses:[[:space:]]*netresearch/[.]github/[.]github/workflows/scorecard[.]yml'
    follow_uses: true
    severity: info
    desc: >-
      OpenSSF Scorecard must be wired up. Satisfied by a local workflow using
      ossf/scorecard-action directly, or a job that delegates to a reusable
      workflow (e.g. netresearch/.github/.github/workflows/scorecard.yml) whose
      upstream body uses ossf/scorecard-action. follow_uses: true expands the
      search to fetch the reusable workflow contents one hop via gh api.

  # === SLSA PROVENANCE ===
  # regex_not with follow_uses: the legacy slsa-github-generator pattern must
  # not appear in either the local workflow OR any one-hop reusable workflow
  # body — otherwise a repo could "hide" the deprecated generator inside a
  # delegated workflow and silently pass.
  - id: GH-21
    type: regex_not
    target: ".github/workflows/*.{yml,yaml}"
    pattern: 'slsa-framework/slsa-github-generator'
    follow_uses: true
    severity: warning
    desc: "Should migrate from slsa-github-generator to actions/attest-build-provenance (cannot be SHA-pinned)"

  # === AUTO-MERGE WORKFLOW CHECKS ===
  - id: GH-23
    type: file_exists
    target: "{.github/workflows/auto-merge-deps.yml,.github/workflows/auto-merge.yml}"
    severity: warning
    desc: "Auto-merge workflow should exist for Dependabot/Renovate PRs"

  # Auto-merge workflows can either:
  #   (a) delegate to the netresearch org reusable workflow
  #       (netresearch/.github/.github/workflows/auto-merge-deps.yml), which
  #       encapsulates the trigger, bot-gating, --auto merging, and dynamic
  #       merge-strategy detection; or
  #   (b) inline the full implementation with pull_request_target: + the
  #       same bot-gating and --auto patterns.
  # GH-24..27 accept either path.

  # Patterns allow optional quoting after `uses:` (YAML accepts uses: foo,
  # uses: 'foo', uses: "foo"). Glob target accepts either auto-merge-deps.yml
  # or auto-merge.yml (GH-23 already treats both as valid filenames).

  # The netresearch reusable-workflow path is unique enough to match without
  # caring about uses:-line quoting (uses: foo, uses: 'foo', uses: "foo" all
  # contain the netresearch/... substring identically).
  - id: GH-24
    type: regex
    target: ".github/workflows/auto-merge*.{yml,yaml}"
    pattern: 'netresearch/\.github/\.github/workflows/auto-merge-deps\.yml|on:[[:space:]]*\n[[:space:]]*pull_request_target:'
    severity: error
    desc: "Auto-merge workflow must delegate to netresearch reusable workflow OR use pull_request_target trigger for bot PR write permissions"

  - id: GH-25
    type: regex
    target: ".github/workflows/auto-merge*.{yml,yaml}"
    pattern: 'netresearch/\.github/\.github/workflows/auto-merge-deps\.yml|github\.event\.pull_request\.user\.login'
    severity: warning
    desc: "Auto-merge should delegate to reusable workflow OR check github.event.pull_request.user.login (not github.actor which changes on reruns)"

  - id: GH-26
    type: regex
    target: ".github/workflows/auto-merge*.{yml,yaml}"
    pattern: 'netresearch/\.github/\.github/workflows/auto-merge-deps\.yml|--auto'
    severity: warning
    desc: "Auto-merge should delegate to reusable workflow OR use gh pr merge --auto to respect branch protection and merge queues"

  - id: GH-27
    type: regex
    target: ".github/workflows/auto-merge*.{yml,yaml}"
    pattern: 'netresearch/\.github/\.github/workflows/auto-merge-deps\.yml|gh api.*repos/\$'
    severity: info
    desc: "Auto-merge should delegate to reusable workflow OR dynamically detect merge strategy from repo settings"

  # === COMPOSITE-ACTION SHA PINNING INSIDE WORKFLOWS ===
  # Reusable-workflow refs like `uses: org/repo/.github/workflows/foo.yml@main`
  # are exempt (see references/reusable-workflow-security.md — internal `@main`
  # is allowed for full reusable workflows). Composite-action refs like
  # `uses: org/repo/.github/actions/foo@main` are NOT exempt: they are resolved
  # at the *consumer's* runner under the consumer's allow-list policy. A
  # consumer that enforces "all actions must be SHA-pinned" will reject a
  # reusable workflow that internally references a composite action by branch
  # or tag, even though the workflow file itself is unchanged. SHA-pin
  # composite-action refs to avoid breaking SHA-pinned consumers.
  # PCRE negative lookahead matches refs that are NOT a 40-char hex SHA.
  # The lookahead requires the 40 hex chars to be followed by quote/comment/
  # whitespace/EOL — without that terminator, refs like `@<40hex>-tag` would
  # spuriously pass because `\b` matches between hex and `-`.
  - id: GH-34
    type: regex_not
    target: ".github/workflows/*.{yml,yaml}"
    pattern: 'uses:\s+["'']?[A-Za-z0-9._-]+/[A-Za-z0-9._-]+/\.github/actions/[^@]+@(?![0-9a-f]{40}(?:["''#\s]|$))'
    severity: error
    desc: >-
      Composite action references inside .github/workflows/*.yml must be
      SHA-pinned (40-char hex). Branch/tag refs (@main, @v1) break consumers
      that enforce SHA pinning when this workflow is called as a reusable
      workflow. See references/reusable-workflow-pitfalls.md.

  # === HARDEN-RUNNER FIRST-STEP CHECK ===
  # Mechanical YAML-AST check via python yaml.safe_load (a regex-only check
  # cannot reliably reason about "first step of each job" across multi-line
  # YAML). Skipped if PyYAML is unavailable. Jobs that are pure
  # reusable-workflow callers (job-level `uses:` instead of `steps:`) are
  # exempt — they have no runner steps to harden.
  - id: GH-35
    type: command
    target: |
      command -v python3 >/dev/null 2>&1 || exit 0
      python3 - <<'PY'
      try:
          import yaml
      except ImportError:
          import sys; sys.exit(0)
      import glob, sys
      bad = []
      for f in sorted(glob.glob('.github/workflows/*.yml')
                      + glob.glob('.github/workflows/*.yaml')):
          try:
              with open(f) as fh:
                  wf = yaml.safe_load(fh)
          except Exception:
              continue
          if not isinstance(wf, dict):
              continue
          for jname, job in (wf.get('jobs') or {}).items():
              if not isinstance(job, dict):
                  continue
              # Skip reusable-workflow callers (no steps array).
              if 'uses' in job and 'steps' not in job:
                  continue
              steps = job.get('steps')
              if not isinstance(steps, list) or not steps:
                  continue
              first = steps[0] if isinstance(steps[0], dict) else {}
              uses = first.get('uses', '') or ''
              if not uses.startswith('step-security/harden-runner'):
                  bad.append(f"{f}::{jname}")
      if bad:
          sys.stderr.write("Jobs missing harden-runner as first step: "
                           + ", ".join(bad) + "\n")
          sys.exit(1)
      sys.exit(0)
      PY
    severity: warning
    desc: >-
      Every workflow job with `steps:` should start with
      `step-security/harden-runner` (audit egress). Jobs that are pure
      reusable-workflow callers (job-level `uses:`) are exempt.

  # === AUTO-APPROVE (pr-quality.yml) COPILOT RACE CONDITION ===
  - id: GH-33
    type: command
    target: |
      # If pr-quality.yml exists, verify it triggers on pull_request_review as
      # well as pull_request_target. Without pull_request_review, the approval
      # job races with Copilot and leaves PRs BLOCKED with empty reviewDecision.
      # See references/auto-merge-guide.md → "Auto-Approve Race Condition
      # with Copilot Reviewer".
      WF=.github/workflows/pr-quality.yml
      test -f "$WF" || exit 0   # not applicable if workflow doesn't exist
      grep -qE '^[[:space:]]*pull_request_review[[:space:]]*:' "$WF"
    severity: warning
    desc: >-
      pr-quality.yml should also trigger on pull_request_review to avoid the
      Copilot auto-approve race condition (PR stuck BLOCKED with empty
      reviewDecision)

  # === BRANCH PROTECTION AUDIT ===
  # GH-30 / GH-31 require GitHub API access (gh CLI + auth) which is outside
  # the assessment runner's command allowlist. Declared as type: gh_api so the
  # runner skips them with a clear evidence string instead of rejecting them.
  # The semantically equivalent LLM-driven audit lives in GH-32 (llm_reviews).
  - id: GH-30
    type: gh_api
    endpoint: "repos/{owner}/{repo}/branches/{default_branch}/protection"
    json_path: ".enforce_admins.enabled"
    severity: info
    desc: >-
      enforce_admins recommended on default branch so admins are also bound
      by required status checks and review requirements. Severity is info
      (not error) because netresearch's org default leaves this off — admins
      retain bypass for emergency response. Tighten to true if your org
      requires admin-bind policy.

  - id: GH-31
    type: gh_api
    endpoint: "repos/{owner}/{repo}/branches/{default_branch}/protection"
    json_path: ".required_conversation_resolution.enabled"
    severity: error
    desc: >-
      required_conversation_resolution must be enabled. Without it, PR
      merges may silently include unresolved bot-reviewer feedback —
      including security issues like token leakage in build logs (see
      netresearch/snipe-it-docker-compose-stack#17 where this gap let a
      HIGH-severity Copilot/gemini-code-assist finding ship to main).
      Apply via skills/github-project/scripts/init-branch-protection.sh
      OWNER/REPO right after `gh repo create` + initial push, before
      opening the first PR (script requires the default branch ref to
      exist; exits 4 on empty repos). Combined with enforce_admins,
      also ensures unresolved threads block ALL merges including admins
      (audited by GH-32 llm_review; runner skips because gh API access
      requires auth).

llm_reviews:
  # === BRANCH PROTECTION + MERGE QUEUE COMPATIBILITY ===
  - id: GH-22
    domain: security
    prompt: |
      Check repository ruleset for merge queue + branch protection compatibility:
      1. If merge_queue is enabled, require_last_push_approval MUST be false
         (merge queue commits dismiss approvals, causing permanent blocks)
      2. If require_code_owner_review is true, verify CODEOWNERS file exists
         on the default branch (enabling without the file blocks all PRs)
      3. For solo-maintainer repos: required_approving_review_count should be 1
         (not 0) paired with an auto-approve workflow

      Check via: gh api repos/OWNER/REPO/rulesets --jq '.[].rules[]'
    severity: error
    desc: "Verify branch protection rules are compatible with merge queue configuration"

  # === AUTO-MERGE CORRECTNESS ===
  - id: GH-28
    domain: ci
    prompt: |
      Verify auto-merge workflow end-to-end correctness:
      1. Trigger must be pull_request_target (not pull_request) — bot PRs
         need write permissions from the base branch context
      2. Bot detection must use github.event.pull_request.user.login
         (not github.actor — actor changes on manual reruns)
      3. Merge command must use --auto flag (respects branch protection,
         merge queues, and required checks)
      4. Merge strategy should be dynamically detected from repo settings
         via gh api, not hardcoded (repos may enable different strategies)
      5. If repo has branch protection requiring reviews, the workflow must
         also approve the PR (gh pr review --approve) before enabling auto-merge
      6. Check for step-security/harden-runner presence
      Report specific issues found.
    severity: warning
    desc: "Verify auto-merge workflow uses correct trigger, bot detection, merge flags, and strategy detection"

  - id: GH-29
    domain: ci
    prompt: |
      Check if pr-quality.yml or auto-approve workflow correctly handles bot accounts:
      1. Bot accounts (dependabot[bot], renovate[bot]) have author_association
         of NONE or CONTRIBUTOR — they are NOT org members/collaborators
      2. If auto-approve checks author_association for OWNER/MEMBER/COLLABORATOR,
         it will NEVER approve bot PRs — this is a common misconfiguration
      3. Correct patterns: check user.login explicitly for known bots,
         OR use gh api collaborators permission check (which works for apps
         with collaborator access)
      4. If branch protection requires approving reviews, bot PRs will be
         permanently BLOCKED without a working auto-approve mechanism
      Report if bot approval flow has this misconfiguration.
    severity: error
    desc: "Verify auto-approve workflow correctly handles bot accounts (author_association is NONE for bots)"

  # === BRANCH PROTECTION ENFORCEMENT AUDIT ===
  - id: GH-32
    domain: security
    prompt: |
      Audit branch protection enforcement on the default branch:
      1. Run: gh api repos/OWNER/REPO/branches/BRANCH/protection --jq '.enforce_admins.enabled'
         Recommended (informational only — see GH-30). When false, repository
         admins can bypass branch protection rules. Netresearch's org default
         leaves this off so admins retain bypass for emergency response;
         tighten to true only if your org requires admin-bind policy. Do NOT
         report this as an error on its own — flag it as info/advisory.
      2. Run: gh api repos/OWNER/REPO/branches/BRANCH/protection --jq '.required_conversation_resolution.enabled'
         Must be true. Without this, unresolved review threads do not block merges.
         This is the primary error-level enforcement check (paired with GH-31).
      3. Note the interaction: enforce_admins=false means admins COULD bypass
         required_conversation_resolution. Surface this as an advisory trade-off,
         not a blocking failure, since it matches the documented org default.
      4. If using rulesets instead of branch protection, check the equivalent:
         gh api repos/OWNER/REPO/rulesets --jq '.[].rules[] | select(.type=="pull_request") | .parameters'
         Look for required_review_thread_resolution: true and bypass_actors being empty.
      Report required_conversation_resolution gaps as errors; report
      enforce_admins gaps as info (advisory).
    severity: error
    desc: "Verify required_conversation_resolution is enabled (error); enforce_admins is advisory only (see GH-30)."

  # === PR REVIEW COMPLETENESS PROCESS CHECK ===
  - id: GH-36
    domain: pr-process
    prompt: |
      When a PR's review feedback is being addressed, before declaring it
      "ready to merge" or "all comments addressed":

      1. Query unresolved review threads via GraphQL (first:100 is the
         GraphQL maximum; for PRs at the cap, paginate with
         pageInfo.hasNextPage / endCursor + after:):
         gh api graphql -f query='query($owner:String!,$repo:String!,$pr:Int!){
           repository(owner:$owner,name:$repo){pullRequest(number:$pr){
             reviewThreads(first:100){
               pageInfo{hasNextPage endCursor}
               nodes{id isResolved comments(first:1){nodes{body path line}}}
             }
           }}
         }' -f owner=OWNER -f repo=REPO -F pr=NUMBER \
            --jq '.data.repository.pullRequest.reviewThreads.nodes
                  | map(select(.isResolved == false))'

      2. The count of unresolved threads must be exactly zero. If
         pageInfo.hasNextPage is true, paginate before concluding.
      3. If non-zero, list each thread with the first comment's body
         (truncated to ~100 chars) plus path/line so the user can see
         exactly what's outstanding.

      Common failure mode: addressing only the threads visible at the top
      of the PR discussion, missing inline-code threads or threads from
      earlier reviewers. The GraphQL query is the single source of truth —
      do not rely on the PR conversation tab alone.

      Report: "All threads resolved" OR "N unresolved thread(s): <list>".
    severity: info
    desc: >-
      Before declaring PR review feedback addressed, verify zero unresolved
      review threads via GraphQL (not just the conversation tab).

  # === SUBJECTIVE CHECKS (require LLM judgment) ===
  - id: GH-15
    domain: repo-health
    rubric: references/llm-rubric.md#badge-order
    severity: warning
    desc: "Verify README badges are in the correct order"

  - id: GH-16
    domain: repo-health
    prompt: |
      Verify the README has a clear structure with these sections:
      - Installation/Setup
      - Usage/Configuration
      - Development (tests, linting)
      - License
      - Credits/Contributors

      Check the actual section headers in README.md and report if it matches.
    severity: info
    desc: "README should have standard structure with key sections"

[
  {
    "name": "setup_branch_protection",
    "prompt": "Set up branch protection for this repo requiring PR reviews and status checks",
    "assertions": [
      {
        "type": "tool_use",
        "tool": "Bash",
        "pattern": "gh api.*repos/.*/branches/.*/protection"
      },
      {
        "type": "content",
        "pattern": "(branch protection|ruleset|required_pull_request_reviews|enforce_admins)"
      }
    ]
  },
  {
    "name": "fix_blocked_pr_merge",
    "prompt": "Fix this blocked PR merge - PR #42 shows BLOCKED status",
    "assertions": [
      {
        "type": "tool_use",
        "tool": "Bash",
        "pattern": "gh api graphql.*mergeStateStatus"
      },
      {
        "type": "content",
        "pattern": "(BLOCKED|reviewDecision|mergeStateStatus|reviewThreads)"
      }
    ]
  },
  {
    "name": "setup_auto_merge_workflow",
    "prompt": "Set up auto-merge for Dependabot and Renovate PRs in this repository",
    "assertions": [
      {
        "type": "content",
        "pattern": "pull_request_target"
      },
      {
        "type": "content",
        "pattern": "(user\\.login|dependabot\\[bot\\]|renovate\\[bot\\])"
      },
      {
        "type": "content",
        "pattern": "--auto"
      }
    ]
  },
  {
    "name": "diagnose_auto_merge_failure",
    "prompt": "Auto-merge is not working on PR #15 - Dependabot PR stays open after checks pass",
    "assertions": [
      {
        "type": "content",
        "pattern": "(pull_request_target|user\\.login|github\\.actor|autoMergeRequest)"
      },
      {
        "type": "content",
        "pattern": "(bypass|allow_auto_merge|merge strategy|--auto)"
      }
    ]
  },
  {
    "name": "solo_maintainer_pr_stuck",
    "prompt": "I'm a solo maintainer and my PRs are stuck on REVIEW_REQUIRED even though I'm the only contributor",
    "assertions": [
      {
        "type": "content",
        "pattern": "(auto-approve|pr-quality|required_approving_review_count)"
      },
      {
        "type": "content",
        "pattern": "(solo maintainer|collaborator|write.*permission|admin)"
      }
    ]
  },
  {
    "name": "setup_codeowners",
    "prompt": "Set up CODEOWNERS for this repository with automatic review assignments",
    "assertions": [
      {
        "type": "content",
        "pattern": "(CODEOWNERS|\\.github/CODEOWNERS)"
      },
      {
        "type": "content",
        "pattern": "(@|review)"
      }
    ]
  },
  {
    "name": "fix_github_actions_failure",
    "prompt": "CI is failing on this repo - the build workflow keeps erroring out on the latest push",
    "assertions": [
      {
        "type": "tool_use",
        "tool": "Bash",
        "pattern": "gh run (list|view)"
      },
      {
        "type": "content",
        "pattern": "(log-failed|rerun|workflow)"
      }
    ]
  },
  {
    "name": "migrate_master_to_main",
    "prompt": "Migrate the default branch from master to main for this repository",
    "assertions": [
      {
        "type": "content",
        "pattern": "(default_branch|default-branch)"
      },
      {
        "type": "content",
        "pattern": "(branch -m|rename|master.*main)"
      }
    ]
  },
  {
    "name": "setup_dependabot",
    "prompt": "Configure Dependabot for a Go project that also uses GitHub Actions",
    "assertions": [
      {
        "type": "content",
        "pattern": "dependabot\\.yml"
      },
      {
        "type": "content",
        "pattern": "(gomod|github-actions|package-ecosystem)"
      }
    ]
  },
  {
    "name": "codeql_default_setup_conflict",
    "prompt": "CodeQL is failing with 'analyses from advanced configurations cannot be processed when default setup is enabled'",
    "assertions": [
      {
        "type": "content",
        "pattern": "(default-setup|not-configured|code-scanning)"
      },
      {
        "type": "tool_use",
        "tool": "Bash",
        "pattern": "gh api.*code-scanning"
      }
    ]
  },
  {
    "name": "signed_commits_merge_failure",
    "prompt": "Merge is failing with 'Rebase merges cannot be automatically signed by GitHub' - how do I fix this?",
    "assertions": [
      {
        "type": "content",
        "pattern": "(squash|merge commit|allow_squash_merge|signed)"
      },
      {
        "type": "content",
        "pattern": "(rebase.*cannot.*sign|merge strategy|auto-detect)"
      }
    ]
  },
  {
    "name": "pr_too_many_commits",
    "prompt": "My PR on a fork shows 38 commits but I only added 1 - the merge base seems wrong",
    "assertions": [
      {
        "type": "content",
        "pattern": "(merge base|close.*reopen|fork)"
      },
      {
        "type": "content",
        "pattern": "(gh pr close|cache|recalculate)"
      }
    ]
  },
  {
    "name": "enforce_admins_audit",
    "prompt": "Audit whether admins can bypass branch protection on the default branch of this repo",
    "assertions": [
      {
        "type": "content",
        "pattern": "enforce_admins"
      },
      {
        "type": "tool_use",
        "tool": "Bash",
        "pattern": "gh api.*protection"
      }
    ]
  },
  {
    "name": "resolve_review_threads",
    "prompt": "PR #23 has unresolved review threads blocking merge - help me find and resolve them",
    "assertions": [
      {
        "type": "content",
        "pattern": "(reviewThreads|isResolved|resolveReviewThread)"
      },
      {
        "type": "tool_use",
        "tool": "Bash",
        "pattern": "gh api graphql"
      }
    ]
  },
  {
    "name": "openssf_scorecard_improvement",
    "prompt": "Our OpenSSF Scorecard score is low - what should we fix first?",
    "assertions": [
      {
        "type": "content",
        "pattern": "(Scorecard|Token-Permissions|Branch-Protection|Pinned-Dependencies)"
      },
      {
        "type": "content",
        "pattern": "(workflow.*write|SHA.*pin|required_approving_review_count)"
      }
    ]
  },
  {
    "name": "workflow_permissions_least_privilege",
    "prompt": "Fix the workflow permissions in our CI - we have write permissions at the workflow level",
    "assertions": [
      {
        "type": "content",
        "pattern": "(job-level|workflow-level|permissions)"
      },
      {
        "type": "content",
        "pattern": "(contents: read|pull-requests: write|least.privilege)"
      }
    ]
  },
  {
    "name": "setup_release_labeling",
    "prompt": "Set up automated release labeling so PRs and issues get labeled when a release is published",
    "assertions": [
      {
        "type": "content",
        "pattern": "(release-labeler|released:v)"
      },
      {
        "type": "content",
        "pattern": "(release.*published|label|announcement)"
      }
    ]
  },
  {
    "name": "merge_queue_troubleshooting",
    "prompt": "PRs keep getting stuck in the merge queue after force-pushing a rebase",
    "assertions": [
      {
        "type": "content",
        "pattern": "(merge queue|stale review|dismiss_stale_reviews)"
      },
      {
        "type": "content",
        "pattern": "(force.push|re-queue|resolveReviewThread|auto-approve)"
      }
    ]
  },
  {
    "name": "copilot_reviewer_race_condition",
    "prompt": "Auto-approve keeps getting skipped and PRs stay REVIEW_REQUIRED - we use Copilot as a reviewer",
    "assertions": [
      {
        "type": "content",
        "pattern": "(race condition|Copilot|pending reviewer)"
      },
      {
        "type": "content",
        "pattern": "(re-run|rerun|auto-approve|COMMENTED)"
      }
    ]
  },
  {
    "name": "workflow_file_pr_cannot_merge",
    "prompt": "A Dependabot PR that updates a GitHub Actions version can't be auto-merged - it modifies workflow files",
    "assertions": [
      {
        "type": "content",
        "pattern": "(\\.github/workflows/|workflow.*files|GITHUB_TOKEN)"
      },
      {
        "type": "content",
        "pattern": "(manual.*merge|workflows.*permission|cannot.*auto-merge)"
      }
    ]
  }
]