From 830e623fa93daabec46113f86efa2edae7726947 Mon Sep 17 00:00:00 2001
From: Micheal Wilkinson <micheal.wilkinson@createfuture.com>
Date: Sat, 21 Mar 2026 13:51:07 +0000
Subject: [PATCH] docs: refine changelog gate documentation formatting and
 descriptions

---
 AGENTS.md    | 14 ++++++++++++--
 CHANGELOG.md |  8 ++++++++
 README.md    |  7 ++++---
 3 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 0a464db..7e4e966 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -229,11 +229,21 @@ Useful optional inputs:
 - `changelog` (default `CHANGELOG.md`)
 - `comment-title` (default `Vociferate Review`)
 - `token` (defaults to workflow token)
+- `enable-changelog-gate` (default `false`) - Enable changelog validation gate
+- `changelog-gate-mode` (default `soft`) - `strict` or `soft` mode for gate
+- `changelog-gate-required-for` (default `code,behavior,security,workflow,tooling`) - Change types requiring entries
+- `changelog-gate-allow-docs-only` (default `true`) - Skip requirement for docs-only PRs
+- `changelog-gate-docs-globs` (default `docs/**,**.md,**.txt,**.rst`) - Docs file patterns
+- `changelog-gate-skip-labels` (default empty) - PR labels that bypass requirement
 
 Primary outputs:
 
-- `comment-id`
-- `comment-url`
+- `comment-id` - Comment ID
+- `comment-url` - Comment URL
+- `gate-passed` - Whether changelog gate validation passed
+- `docs-only` - Whether PR is docs-only
+- `unreleased-additions-count` - Number of Unreleased additions detected
+- `gate-failure-reason` - Reason for gate failure, if applicable
 
 ## Guardrails For Agents
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b6d5a50..5e670f3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,14 @@ A `### Breaking` section is used in addition to Keep a Changelog's standard sect
 
 ### Added
 
+- Added changelog gate validation to `decorate-pr` action for enforcing changelog updates on qualifying code changes.
+- Changelog gate modes: `strict` (fails job on violation) and `soft` (warns via PR comment).
+- Docs-only PR exemption with customizable glob patterns for documentation files.
+- PR label-based exemptions for changelog gate (example: `skip-changelog`).
+- Precise diff parsing: validates only added lines within the Unreleased section.
+- Gate decision outputs: `gate-passed`, `docs-only`, `unreleased-additions-count`, `gate-failure-reason` for reuse downstream.
+- Integrated remediation guidance in PR comments showing how to add changelog entries.
+
 ### Changed
 
 ### Removed
diff --git a/README.md b/README.md
index 1065972..6bed39a 100644
--- a/README.md
+++ b/README.md
@@ -176,13 +176,14 @@ Enable changelog validation to enforce that code changes include `Unreleased` ch
     badge-url: ${{ steps.coverage.outputs.badge-url }}
     enable-changelog-gate: true
     changelog-gate-mode: strict
-    changelog-gate-required-for: 'code,behavior,security,workflow,tooling'
+    changelog-gate-required-for: "code,behavior,security,workflow,tooling"
     changelog-gate-allow-docs-only: true
-    changelog-gate-docs-globs: 'docs/**,**.md,**.txt,**.rst'
-    changelog-gate-skip-labels: 'skip-changelog'
+    changelog-gate-docs-globs: "docs/**,**.md,**.txt,**.rst"
+    changelog-gate-skip-labels: "skip-changelog"
 ```
 
 The gate automatically:
+
 - Parses diffs to detect docs-only PRs (skips requirement for doc-only changes)
 - Counts `Unreleased` additions using section-aware parsing (ignores edits outside the section)
 - Checks PR labels for skip exemptions (for example, `skip-changelog`)