feat: add decorate-pr composite action for pull request review decoration

AGENTS.md

@@ -12,6 +12,7 @@ Published composite actions:
 - `git.hrafn.xyz/aether/vociferate/prepare@v1.0.1`
 - `git.hrafn.xyz/aether/vociferate/publish@v1.0.1`
 - `git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.1`
+- `git.hrafn.xyz/aether/vociferate/decorate-pr@v1.0.1`
 
 ## Action Selection Matrix
 
@@ -20,6 +21,7 @@ Use this when deciding which action to call:
 - Choose `prepare` when you need to update changelog/version files, commit, and push a release tag.
 - Choose `publish` when a tag already exists and you need to create or update release notes/assets.
 - Choose `coverage-badge` after tests have produced `coverage.out` and you need coverage artefacts uploaded.
+- Choose `decorate-pr` to annotate pull requests with coverage information and unreleased changelog entries.
 - Choose root `vociferate` for direct recommend/prepare logic without commit/tag/push behavior.
 
 ## Preconditions
@@ -139,6 +141,34 @@ jobs:
           artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
 ```
 
+### 4. Decorate Pull Request With Coverage and Changes
+
+```yaml
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    env:
+      AWS_ACCESS_KEY_ID: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET }}
+      AWS_DEFAULT_REGION: ${{ vars.ARTEFACT_BUCKET_REGION }}
+      AWS_EC2_METADATA_DISABLED: true
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run tests with coverage
+        run: go test -covermode=atomic -coverprofile=coverage.out ./...
+      - id: badge
+        uses: git.hrafn.xyz/aether/vociferate/coverage-badge@v1.0.0
+        with:
+          artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
+          artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
+      - name: Decorate PR
+        uses: git.hrafn.xyz/aether/vociferate/decorate-pr@v1.0.0
+        with:
+          coverage-percentage: ${{ steps.badge.outputs.total }}
+          badge-url: ${{ steps.badge.outputs.badge-url }}
+```
+
 ## Inputs And Outputs Cheatsheet
 
 ### prepare
@@ -186,6 +216,24 @@ Primary outputs:
 - `report-url`
 - `badge-url`
 
+### decorate-pr
+
+Required inputs:
+
+- `coverage-percentage` (0-100, typically from coverage-badge action)
+- `badge-url` (SVG badge URL, typically from coverage-badge action)
+
+Useful optional inputs:
+
+- `changelog` (default `CHANGELOG.md`)
+- `comment-title` (default `Vociferate Review`)
+- `token` (defaults to workflow token)
+
+Primary outputs:
+
+- `comment-id`
+- `comment-url`
+
 ## Guardrails For Agents
 
 Use these rules to avoid common automation mistakes: