Add native sticky PR comment infrastructure for changelog validation

[Mpdreamz]

docs-builder gains the full native infrastructure to post and update a sticky PR comment from changelog validation — so any repo can opt in by copying one workflow file, without needing the full changelog-submit chain.

Affects: Release notes, CLI

Why

Repos on the minimal release-notes path (validate-labels, evaluate-pr) get a red check when labels are wrong but no comment explaining which label is missing. The rich diagnostic already exists as JavaScript in changelog/submit/apply/scripts/, but it is reachable only from the apply job — repos without a changelog-file workflow never see it. Fork PRs make this worse: GitHub forces the token read-only on pull_request from a fork regardless of permissions:, so commenting must happen in a workflow_run job with a separate token. This PR lays the foundation so a single release-notes-comments.yml file can cover both paths.

What

Rename ChangelogArtifactMetadata → GithubDecisionMetadata

The old name implied the record was about the artifact file. Every field in it steers a GitHub Actions decision: CanCommit, HeadRef/HeadSha for the checkout step, LabelTable/Status for the comment body. The rename is wire-safe — PropertyNamingPolicy = JsonKnownNamingPolicy.SnakeCaseLower derives JSON names from properties, so existing metadata.json files still deserialize. Two new optional fields are added: CommitOutcome (enum None | Committed | Failed) and CommittedFile.

Decision metadata written on CI from validate-labels and evaluate-pr

Both commands now write .artifacts/changelog-decision/metadata.json when GITHUB_ACTIONS is set and a PR number is supplied. The write is purely additive — exit codes, existing step outputs, and the should-comment-success/should-comment-failure outputs are unchanged. .artifacts is already gitignored and allow-listed by RunnerTempFileSystem.

Two hidden CLI commands: changelog github-decision and changelog github-comment

github-decision reads the metadata file and stamps CommitOutcome + CommittedFile into it. github-comment reads the file and posts or updates the PR comment. Both are [Hidden] — absent from --help and autocomplete, but visible in __schema with hidden: true and fully functional when invoked. Schema regenerated.

Sticky-comment upsert with pagination and JS bidirectional compatibility

GitHubCommentService.UpsertStickyCommentAsync paginates through all PR comments (100 per page) to find the existing sticky comment. It matches on the <!-- docs-builder:changelog --> marker at the end of the body, or the legacy ### 📋 Changelog prefix that the existing comment-helper.js writes. During the overlap window both implementations converge on one comment; with the marker at the end rather than the start, the JS startsWith check still matches.

Comment body renderer

ChangelogCommentRenderer ports all four JS body variants: entry-committed (blob + edit links with URL-encoded path components), comment-only (YAML fenced with guidance variants for commit-failed, fork, or informational), cannot-generate (headline + label tables + skip-label list), and resolved (edits a stale failure comment to a short success body so the PR is never left with a misleading comment). Code-fence escaping uses the longest backtick run in content + 1; inline code pads when the value starts or ends with a backtick. Body is capped at GitHub's 65 536-character limit.

Verify

dotnet test tests/Elastic.Changelog.Tests/
# ChangelogLabelValidationServiceTests — metadata write on CI
# GitHubCommentServiceTests — pagination, legacy-prefix match, bidirectional compat
# ChangelogCommentRendererTests — all four body variants, fence escaping, truncation
# ChangelogGithubCommentServiceTests — selection table (committed / failed / fork / no-label / resolved)
# ChangelogGithubDecisionServiceTests — round-trip preserves all other fields

dotnet run --project src/tooling/docs-builder -- changelog --help
# github-decision and github-comment must NOT appear

dotnet run --project src/tooling/docs-builder -- __schema | grep -A2 '"github-decision"'
# must appear with "hidden": true

Stack: 1 of 4. PR 2 adds release-notes-comments.yml to docs-actions and uploads the artifact from release-notes.yml. PR 3 strips the JS from submit/apply (coordinated with elastic/cloud). PR 4 drops should-comment-success / should-comment-failure once nothing reads them.

Out of scope: should-comment-success / should-comment-failure step outputs are intentionally kept. Removing them now would silently stop elastic/cloud's changelog-submit comment steps from firing.

[github-actions]

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3993/

Sample changed pages:

• docs/cli/changelog/cmd-evaluate-pr.md
• docs/cli/changelog/cmd-validate-labels.md