feat: auto-label PRs touching aidlc-rules/ with codebuild label (#158)

* feat: auto-label PRs using actions/labeler

Adds an auto-label job to the Pull Request Validation workflow using
actions/labeler v6.0.1. Labels are applied based on changed file paths
and removed when those files are no longer changed (sync-labels: true).

Works for fork PRs via pull_request_target — no checkout of fork code,
the action only reads file paths from the API.

Initial label rules:
- codebuild: aidlc-rules/**
- documentation: **/*.md, docs/**
- workflows: .github/**

* refactor: rename label to 'rules', refine labeler config

- Rename 'codebuild' label to 'rules' in codebuild.yml (conditions,
  reminder text, and marker)
- Rename 'workflows' label to 'github' matching .github/**
- Scope 'documentation' label to *.md files NOT under aidlc-rules/
  using all-globs-to-any-file with negation

* fix: add issues:write permission for auto-label job

Allows actions/labeler to create labels that don't yet exist in the
repository, preventing failures on first use of a new label rule.

* docs: update administrative guide for auto-labeling and rules label

- Rename all 'codebuild' label references to 'rules' (preserving
  CodeBuild service/environment references)
- Add auto-label job to Pipeline 3 diagram and workflow reference
- Document label rules table (rules, documentation, github)
- Add actions/labeler to external actions table
- Add auto-label job to permissions table
- Add labeler.yml to repository tree diagram

---------

Co-authored-by: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com>

Author: scottschreckengaust

.github/labeler.yml

@@ -0,0 +1,16 @@
+# Auto-label configuration for actions/labeler
+# See https://github.com/actions/labeler#match-object for syntax
+
+rules:
+- changed-files:
+  - any-glob-to-any-file: 'aidlc-rules/**'
+
+documentation:
+- changed-files:
+  - all-globs-to-any-file:
+    - '**/*.md'
+    - '!aidlc-rules/**'
+
+github:
+- changed-files:
+  - any-glob-to-any-file: '.github/**'

.github/workflows/codebuild.yml

@@ -25,7 +25,7 @@ concurrency:
 
 env:
   CODEBUILD_PROJECT_NAME: ${{ vars.CODEBUILD_PROJECT_NAME || 'codebuild-project' }}
-  LABEL_REMINDER_MARKER: codebuild-label-reminder
+  LABEL_REMINDER_MARKER: rules-label-reminder
 
 permissions:
   actions: none
@@ -48,17 +48,17 @@ jobs:
   label-reminder:
     if: >-
       github.event_name == 'pull_request'
-      && !contains(github.event.pull_request.labels.*.name, 'codebuild')
+      && !contains(github.event.pull_request.labels.*.name, 'rules')
 
     permissions:
       pull-requests: write
 
     runs-on: ubuntu-latest
 
     steps:
-      - name: Warn about missing codebuild label
+      - name: Warn about missing rules label
         run: |
-          echo "::warning::This PR changes aidlc-rules/ but does not have the 'codebuild' label. Add the label to trigger the CodeBuild evaluation pipeline."
+          echo "::warning::This PR changes aidlc-rules/ but does not have the 'rules' label. Add the label to trigger the CodeBuild evaluation pipeline."
 
       - name: Comment on PR
         if: github.event.pull_request.head.repo.full_name == github.repository
@@ -76,9 +76,9 @@ jobs:
             exit 0
           fi
           BODY="<!-- $MARKER -->
-          > **Note:** This PR changes \`aidlc-rules/\` but the \`codebuild\` label has not been applied.
+          > **Note:** This PR changes \`aidlc-rules/\` but the \`rules\` label has not been applied.
           >
-          > A maintainer must add the **codebuild** label to trigger the CodeBuild evaluation pipeline.
+          > A maintainer must add the **rules** label to trigger the CodeBuild evaluation pipeline.
           > Once labeled, subsequent pushes will re-trigger the build automatically."
           gh pr comment "$PR_NUMBER" --repo "$REPO" --body "$BODY"
 
@@ -90,7 +90,7 @@ jobs:
   label-cleanup:
     if: >-
       github.event_name == 'pull_request'
-      && contains(github.event.pull_request.labels.*.name, 'codebuild')
+      && contains(github.event.pull_request.labels.*.name, 'rules')
       && github.event.pull_request.head.repo.full_name == github.repository
 
     permissions:
@@ -123,7 +123,7 @@ jobs:
   build:
     if: >-
       github.event_name != 'pull_request'
-      || contains(github.event.pull_request.labels.*.name, 'codebuild')
+      || contains(github.event.pull_request.labels.*.name, 'rules')
     environment: codebuild
 
     permissions:

.github/workflows/pull-request-lint.yml

@@ -165,6 +165,19 @@ jobs:
             test
           requireScope: false
 
+  auto-label:
+    name: Auto-label
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    if: github.event_name == 'pull_request_target'
+    steps:
+      - uses: actions/labeler@634933edcd8ababfe52f92936142cc22ac488b1b # v6.0.1
+        with:
+          sync-labels: true
+
   contributorStatement:
     name: Require Contributor Statement
     runs-on: ubuntu-latest

docs/ADMINISTRATIVE_GUIDE.md

@@ -44,6 +44,7 @@ awslabs/aidlc-workflows/
 ├── .github/
 │   ├── CODEOWNERS
 │   ├── ISSUE_TEMPLATE/           # Bug, feature, RFC, docs templates
+│   ├── labeler.yml               # Auto-label rules (path → label mapping)
 │   ├── pull_request_template.md  # PR template with contributor statement
 │   └── workflows/
 │       ├── codebuild.yml         # CI via AWS CodeBuild
@@ -116,7 +117,7 @@ The release flow is **changelog-first**: the CHANGELOG is updated *before* the t
 flowchart LR
     A["git push main"] --> B{{"Manual approval\n(codebuild environment)"}}
     C["workflow_dispatch\n(no tag input)"] --> B
-    D["pull_request\n(aidlc-rules/** changed)"] --> E{"codebuild\nlabel?"}
+    D["pull_request\n(aidlc-rules/** changed)"] --> E{"rules\nlabel?"}
     E -->|yes| F["label-cleanup\n(remove reminder comment)"]
     F --> B
     E -->|no| I["label-reminder\n(warning + PR comment)"]
@@ -135,9 +136,10 @@ flowchart TD
     B --> E["fail-by-label\n(do-not-merge label)"]
     A --> F["validate\n(conventional commit title)"]
     A --> G["contributorStatement\n(acknowledgment in PR body)"]
+    A --> H["auto-label\n(actions/labeler)"]
 ```
 
-`pull-request-lint.yml` runs on every PR targeting `main` and on merge queue checks. It enforces four gates: conventional commit PR titles, the contributor statement from the PR template, a configurable merge-halt mechanism, and a do-not-merge label check. The workflow uses `pull_request_target` (not `pull_request`) so it runs in the context of the base branch — this is safe because it never checks out PR code.
+`pull-request-lint.yml` runs on every PR targeting `main` and on merge queue checks. It enforces four gates (conventional commit PR titles, the contributor statement from the PR template, a configurable merge-halt mechanism, and a do-not-merge label check) and automatically applies labels based on changed file paths. The workflow uses `pull_request_target` (not `pull_request`) so it runs in the context of the base branch — this is safe because it never checks out PR code and the `auto-label` job uses `actions/labeler` which only reads file paths from the API.
 
 ---
 
@@ -216,24 +218,24 @@ flowchart TD
 
 **Purpose:** Runs an AWS CodeBuild project, downloads primary and secondary artifacts from S3, caches them in GitHub Actions cache, uploads them as workflow artifacts, and (when triggered from a `v*` tag) attaches them to the GitHub Release.
 
-**PR label gate:** For `pull_request` events, the workflow only fires when files under `aidlc-rules/**` are changed (via `paths` filter) and the `build` job only runs when the `codebuild` label is present on the PR (via `contains(github.event.pull_request.labels.*.name, 'codebuild')`). The trigger includes `types: [opened, synchronize, reopened, labeled]` so that subsequent pushes to a labeled PR re-trigger the build automatically. `push`, `workflow_dispatch`, and tag events bypass the label check entirely.
+**PR label gate:** For `pull_request` events, the workflow only fires when files under `aidlc-rules/**` are changed (via `paths` filter) and the `build` job only runs when the `rules` label is present on the PR (via `contains(github.event.pull_request.labels.*.name, 'rules')`). The `rules` label is applied automatically by the `auto-label` job in `pull-request-lint.yml` (see [Pull Request Validation Workflow](#pull-request-validation-workflow-pull-request-lintyml)). The trigger includes `types: [opened, synchronize, reopened, labeled]` so that subsequent pushes to a labeled PR re-trigger the build automatically. `push`, `workflow_dispatch`, and tag events bypass the label check entirely.
 
-**Job: `label-reminder`** (PR only, no `codebuild` label)
+**Job: `label-reminder`** (PR only, no `rules` label)
 
 | Step | Name                             | Action                                                                                     |
 | ---- | -------------------------------- | ------------------------------------------------------------------------------------------ |
-| 1    | Warn about missing codebuild label | Emits a `::warning::` annotation visible in the Actions summary                           |
+| 1    | Warn about missing rules label   | Emits a `::warning::` annotation visible in the Actions summary                           |
 | 2    | Comment on PR                    | Posts a one-time PR comment (idempotent — skips if the reminder comment already exists)     |
 
-This job runs only for `pull_request` events where `aidlc-rules/**` changed but the `codebuild` label is absent. It alerts maintainers and reviewers that the evaluation pipeline was not triggered. The comment is posted once per PR using an HTML comment marker (`<!-- codebuild-label-reminder -->`) to avoid duplicates.
+This job runs only for `pull_request` events where `aidlc-rules/**` changed but the `rules` label is absent. It alerts maintainers and reviewers that the evaluation pipeline was not triggered. The comment is posted once per PR using an HTML comment marker (`<!-- rules-label-reminder -->`) to avoid duplicates. In normal operation, the `auto-label` job in `pull-request-lint.yml` applies the `rules` label automatically, so this job serves as a fallback safety net.
 
-**Job: `label-cleanup`** (PR only, `codebuild` label present)
+**Job: `label-cleanup`** (PR only, `rules` label present)
 
 | Step | Name                          | Action                                                                                   |
 | ---- | ----------------------------- | ---------------------------------------------------------------------------------------- |
 | 1    | Remove label reminder comment | Finds and deletes the `label-reminder` PR comment (no-op if it doesn't exist)            |
 
-This job runs when the `codebuild` label is applied, immediately removing the reminder comment without waiting for the `codebuild` environment approval gate.
+This job runs when the `rules` label is applied, immediately removing the reminder comment without waiting for the `codebuild` environment approval gate.
 
 **Job: `build`**
 
@@ -351,6 +353,18 @@ Only runs for `pull_request` and `pull_request_target` events (not `merge_group`
 
 Allowed types: `fix`, `feat`, `build`, `chore`, `ci`, `docs`, `style`, `refactor`, `perf`, `test`. Scopes are optional (`requireScope: false`).
 
+**Job: `auto-label` ("Auto-label")**
+
+Only runs for `pull_request_target` events. Uses [`actions/labeler`](https://github.com/actions/labeler) v6.0.1 to automatically apply and remove labels based on changed file paths. Label rules are defined in `.github/labeler.yml`:
+
+| Label           | Path Pattern                                    | Description                                      |
+| --------------- | ----------------------------------------------- | ------------------------------------------------ |
+| `rules`         | `aidlc-rules/**`                                | Triggers CodeBuild evaluation pipeline           |
+| `documentation` | `**/*.md` (excluding `aidlc-rules/**`)          | Non-rules markdown file changes                  |
+| `github`        | `.github/**`                                    | Workflow, template, or config changes             |
+
+With `sync-labels: true`, labels are automatically removed when the matching files are no longer in the PR diff (e.g., after a rebase drops those changes). New label rules can be added by editing `.github/labeler.yml` — no workflow changes required.
+
 **Job: `contributorStatement` ("Require Contributor Statement")**
 
 Only runs for `pull_request` and `pull_request_target` events. Skipped for bot accounts (`dependabot[bot]`, `github-actions[bot]`, `github-actions`, `aidlc-workflows`). Verifies the PR body contains the contributor acknowledgment text from `.github/pull_request_template.md`:
@@ -361,6 +375,7 @@ Only runs for `pull_request` and `pull_request_target` events. Skipped for bot a
 
 | Action                                  | Version | SHA                                        |
 | --------------------------------------- | ------- | ------------------------------------------ |
+| `actions/labeler`                       | v6.0.1  | `634933edcd8ababfe52f92936142cc22ac488b1b` |
 | `amannn/action-semantic-pull-request`   | v6.1.1  | `48f256284bd46cdaab1048c3721360e808335d50` |
 | `actions/github-script`                 | v8.0.0  | `ed597411d8f924073f98dfc5c65a23a2325f34cd` |
 
@@ -421,9 +436,10 @@ All variables have sensible defaults via `${{ vars.VAR || 'default' }}` syntax,
 
 | Workflow                | Job                    | Permissions                                            | Rationale                                                      |
 | ----------------------- | ---------------------- | ------------------------------------------------------ | -------------------------------------------------------------- |
-| `codebuild.yml`         | `label-reminder`       | `pull-requests: write`                                 | Post reminder comment when `codebuild` label is missing        |
-| `codebuild.yml`         | `label-cleanup`        | `pull-requests: write`                                 | Delete reminder comment when `codebuild` label is applied      |
+| `codebuild.yml`         | `label-reminder`       | `pull-requests: write`                                 | Post reminder comment when `rules` label is missing            |
+| `codebuild.yml`         | `label-cleanup`        | `pull-requests: write`                                 | Delete reminder comment when `rules` label is applied          |
 | `codebuild.yml`         | `build`                | `actions: write`, `contents: write`, `id-token: write` | Cache management, release asset upload, OIDC token for AWS STS |
+| `pull-request-lint.yml` | `auto-label`           | `contents: read`, `issues: write`, `pull-requests: write` | Apply/remove labels based on changed file paths; `issues: write` allows creating labels that don't yet exist |
 | `pull-request-lint.yml` | `get-pr-info`          | `contents: read`, `pull-requests: read`                | Read PR metadata and labels via API                            |
 | `pull-request-lint.yml` | `check-merge-status`   | `pull-requests: read`                                  | Read PR state for merge gate checks                            |
 | `pull-request-lint.yml` | `validate`             | `pull-requests: read`                                  | Read PR title for conventional commit validation               |
@@ -441,7 +457,7 @@ Both `codebuild.yml` and `pull-request-lint.yml` follow a **deny-all-then-grant*
 | **AWS authentication**      | OIDC-based role assumption via `id-token: write` — no static credentials stored                                                                                   |
 | **Least-privilege tokens**  | `codebuild.yml` and `pull-request-lint.yml` explicitly deny all 16 permission scopes at workflow level, grant only required scopes at job level                   |
 | **Environment protection**  | `codebuild` environment gates AWS credential access with potential reviewer/branch rules                                                                          |
-| **Label-gated CI**          | `codebuild.yml` requires the `codebuild` label on PRs and only triggers for `aidlc-rules/**` changes, preventing unnecessary builds and environment approval prompts |
+| **Label-gated CI**          | `codebuild.yml` requires the `rules` label on PRs and only triggers for `aidlc-rules/**` changes, preventing unnecessary builds and environment approval prompts. The label is applied automatically by the `auto-label` job in `pull-request-lint.yml` |
 | **Concurrency control**     | `codebuild.yml` and `pull-request-lint.yml` cancel in-progress runs for the same branch                                                                          |
 | **Safe PR trigger**         | `pull-request-lint.yml` uses `pull_request_target` but never checks out PR code — only inspects metadata (title, labels, body)                                    |
 | **Injection-safe inputs**   | Zero `${{ }}` expression interpolation in `run:` blocks — all dynamic values (`github.ref_name`, `github.repository`, `env.*`, event inputs) passed via step-level `env:` or auto-exported workflow `env:` variables |