docs+ci(changelog): AI-draft entries for merges that skip the changelog, and backfill the gaps

[macanderson]

Why

An audit of the 22 merges since v0.1.0 whose PR numbers never appear in CHANGELOG.md found 9 user-visible changes with no entry at all — including the OCP → CGP rename itself (#1), the repo's biggest breaking change. (7 others were covered under issue numbers; 6 were internal chores.) [Unreleased] had also accumulated duplicate category headings — two ### Added, two ### Changed, two ### Fixed — from PRs appending their own blocks.

Go-forward: a changelog that cannot silently fall behind

• .github/workflows/changelog.yml — on every push to main, measures the gap since the last commit that touched CHANGELOG.md. If a merge landed without touching it, drafts the missing entries from the merge's actual diff (.github/scripts/changelog-ai.sh) and proposes them as a bot/changelog PR — a draft for human review, never a direct push.
• Self-resetting: merging the bot PR touches CHANGELOG.md, emptying the gap. Each run regenerates the whole current gap, so force-updates lose nothing and a stale bot PR is simply superseded by a fuller one.
• Degrade-open: no AI_GATEWAY_API_KEY secret, a failed call, or an internal-only gap → a log line, never a red check and never a PR.

Backfill (written from each PR's diff, in the file's voice)

• Breaking: the OCP → Context Graph Protocol rename (Rename Open Context Protocol (OCP) → Context Graph Protocol #1)
• Frame identity, deterministic composition, usage reports (feat: context-reuse guarantees — deterministic composition, usage reports, consent scopes, context/verify (#23–#26) #32)
• Golden wire fixtures with attested digests (test(protocol): publish context graph golden fixtures #35)
• ADR 0007 — the protocol/product boundary (docs: reconcile adaptive-context bundle with the protocol spec (#27) #61, P1: Reconcile the adaptive-context bundle (Context Frame spec, directive schema, CGP build prompt) with the protocol spec #27)
• Composition conformance for downstream hosts + the canary scheduled-run gate (feat(conformance): certify a downstream host's composition, and export the C7 rule #70)

Three other audit hits (#68, #69, #71) turned out to be already covered by newer entries and were deliberately left alone. Duplicate category headings merged into one per category, Keep-a-Changelog order — all 39 existing bullets preserved verbatim.

To activate drafting

Add the AI_GATEWAY_API_KEY repo secret (same key stella's release notes use). Until then the workflow no-ops with a log line.

Summary by Sourcery

Keep the changelog aligned with main by auto-drafting missing entries for merges and backfilling past gaps.

Enhancements:

• Introduce an AI-powered changelog drafting script that summarizes user-visible changes from a git range, while safely degrading to no-op when there is no key, failures, or internal-only changes.

CI:

• Add a changelog GitHub Actions workflow that measures commits since CHANGELOG.md was last touched, drafts entries from their diffs via an AI script, and proposes them as a bot PR instead of pushing directly to main.

Documentation:

• Document the convention that PRs must record user-visible changes under the Unreleased section and that a bot can draft missing entries from diffs.
• Backfill missing changelog entries for past user-visible changes, including the OCP → Context Graph Protocol rename, frame identity and deterministic composition, golden wire fixtures, ADR 0007, and composition conformance with downstream canary behavior.

[sourcery-ai]

Reviewer's Guide

Adds an AI-assisted workflow to automatically draft changelog entries for merges that skipped updating CHANGELOG.md, and backfills missing entries while normalizing the Unreleased section layout.

Sequence diagram for the changelog AI-drafting workflow on pushes to main

sequenceDiagram
  participant GithubActions
  participant Git
  participant changelog_ai_sh
  participant AIGateway
  participant GitHubAPI

  GithubActions->>Git: git log -1 HEAD -- CHANGELOG.md
  Git-->>GithubActions: last_changelog_commit (base)
  GithubActions->>Git: git rev-list --count base..HEAD
  Git-->>GithubActions: gap_count

  alt gap_count == 0
    GithubActions-->GithubActions: [no gap, workflow ends]
  else gap_count > 0
    GithubActions->>changelog_ai_sh: run changelog-ai.sh base..HEAD
    changelog_ai_sh->>Git: git log / git diff (range base..HEAD)
    Git-->>changeling_ai_sh: commits, stat, diff
    alt AI_GATEWAY_API_KEY set
      changelog_ai_sh->>AIGateway: POST /v1/chat/completions (prompt, diff)
      AIGateway-->>changelog_ai_sh: changelog markdown bullets
      changelog_ai_sh-->GithubActions: entries file path

      alt entries file non-empty
        GithubActions->>Git: insert entries under [Unreleased], commit
        GithubActions->>GitHubAPI: push bot/changelog branch
        GithubActions->>GitHubAPI: gh pr list/edit/create
        GitHubAPI-->>GithubActions: bot PR opened/updated
      else entries file empty
        GithubActions-->GithubActions: [internal-only or invalid response, no PR]
      end
    else AI_GATEWAY_API_KEY missing or call fails
      changelog_ai_sh-->GithubActions: [prints nothing]
      GithubActions-->GithubActions: [log line, no PR]
    end
  end

Loading

File-Level Changes

Change	Details	Files
Introduce a GitHub Actions workflow that measures commits since the last changelog edit and opens/refreshes a bot PR with AI-drafted entries when user-visible gaps exist.	Add .github/workflows/changelog.yml to run on pushes to main and manual dispatch Compute the git range from the last commit that touched CHANGELOG.md to HEAD and skip if there is no gap Call an AI drafting script over the computed diff range, capturing its markdown output when available Create or update a bot/changelog branch that inserts drafted bullets under the Unreleased heading in CHANGELOG.md Use gh CLI to create or edit a draft PR describing the gap and how the entries were generated, with graceful no-op behavior when drafting produces nothing	.github/workflows/changelog.yml
Add a Bash script that uses the repo’s diff and commit metadata to prompt an AI model and emit Keep-a-Changelog style bullets only for user-visible changes.	Implement .github/scripts/changelog-ai.sh to accept a git range and gather commit subjects, bodies, diff stat, and truncated diff excluding lockfiles Construct a detailed prompt describing the repository, desired changelog style, and visibility criteria Invoke an external AI gateway using curl with configurable model and API key, handling timeouts and failures without breaking the caller Post-process the AI response to strip code fences, trim whitespace, and validate that it looks like changelog markdown, otherwise emit nothing Treat a sentinel NOTHING response as "internal-only" and exit quietly	.github/scripts/changelog-ai.sh
Update CHANGELOG.md to document the new auto-drafting workflow, consolidate duplicate Unreleased section headings, and backfill missing entries for past user-visible changes.	Add narrative at the top of CHANGELOG.md describing the PR convention and the new changelog.yml plus changelog-ai.sh drafting process Merge duplicate Added/Changed/Fixed headings under the Unreleased section into single headings while preserving all existing bullets Insert backfilled bullets for previously unrecorded user-visible changes, including the OCP→Context Graph Protocol rename, frame identity and usage reports, golden wire fixtures, ADR 0007, and composition conformance plus canary behavior Ensure new bullets are placed under the appropriate Added/Changed/Fixed headings per Keep-a-Changelog ordering Remove now-redundant duplicate heading blocks from the lower part of the file so the structure is normalized	CHANGELOG.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery