/draft-release-notes

name: draft-release-notes
description: Draft or refresh Omnigent package release notes for the next version using the existing GitHub Actions preview, merged PR material, and release-note composer. Use when preparing release highlights before a tag exists or reviewing a release-note draft; does not cut or publish a release.

Draft the next Omnigent release notes

Produce a reviewable release-note draft and a complete changelog preview for a specific version and commit range. Use the repository's existing generation contract and keep the result unpublished. A drafting request covers the preview workflow and local artifacts; tags, version bumps, changelog PRs, and GitHub Release writes require a request for those actions.

Run commands from an Omnigent checkout with Git history, authenticated `gh`, and Python 3.11+ with `packaging`. Preserve unrelated changes; use an isolated worktree of the trusted default branch if the current checkout differs.

Resolve the inputs

Read the current sources before drafting; their contract takes precedence over the examples below:

• `.github/workflows/draft-release-notes.yml`: preview inputs and artifacts.
• `.github/agents/release-notes-drafter/config.yaml`: highlight format and voice.
• `.github/scripts/changelog/generate.py`: release range, PR harvest, and credits.
• `.github/scripts/changelog/compose_notes.py`: citation validation and footer.

Inspect a recent final GitHub Release for editorial style. Use the version and cutoff requested by the user. If omitted, infer the next version from `pyproject.toml` and final releases and state that assumption; ask only if those sources leave materially different choices.

When refreshing a reviewed draft, read it first and generate a separate candidate. Preserve the user's editorial scope, wording, and verified contributor additions unless the new range or their instructions require a change; regenerating from raw highlights can otherwise discard those edits.

Refresh remote refs and tags. Select the previous final `vX.Y.Z` tag using `generate.previous_final_tag` and the intended version, rather than the newest nightly/RC tag or release publication date. Honor an explicit base override. For an uncut release, pin the current remote `main` SHA, or the user's chosen cutoff, as the range head. For an existing release tag, use its commit. Do not create a tag just to make the generator accept the upcoming version.

Set `notes_repo` to `omnigent-ai/omnigent`, `notes_version` to the intended version, `notes_head` to that full commit SHA, and `notes_base` to the verified base ref. Record the base SHA too. Keep these fixed throughout one draft. Create an output directory outside the tracked tree:

notes_dir="$(mktemp -d "${TMPDIR:-/tmp}/omnigent-release-notes.XXXXXX")"

Record the version, base ref/SHA, head SHA, and snapshot time with timezone in a companion provenance file. Keep a planned release date separate from the snapshot and commit dates; resolve relative dates in the user's timezone.

Run the existing preview

Always force `dry_run=true`, including when the target tag already exists. The workflow's `auto` mode can write a changelog PR for final version tags. The input named `tag` also accepts a commit SHA when `base` is supplied:

gh workflow run draft-release-notes.yml --repo "$notes_repo" --ref main \
  -f tag="$notes_head" -f base="$notes_base" -f dry_run=true
gh run list --repo "$notes_repo" --workflow draft-release-notes.yml \
  --event workflow_dispatch --limit 10 \
  --json databaseId,createdAt,headSha,status,conclusion,url

Identify the dispatched run by actor and dispatch time; do not assume the newest result belongs to this request. Set `notes_run` to its ID and poll its status until it completes. Verify its **Resolve tag and guard** output names the intended head/base and `dry_run=true`. Record its URL and workflow `headSha`, which may differ from the release range head. Confirm the write steps were skipped, then download its artifacts:

gh run download "$notes_run" --repo "$notes_repo" \
  --name "draft-release-notes-${notes_head}-${notes_run}" \
  --dir "$notes_dir/ci"

Inspect `release_notes.md` and, when present, `draft_out.txt`. A successful run does not guarantee highlights: missing LLM credentials or invalid output can leave only community thanks and the changelog link. If dispatch or the drafter fails, inspect the failure and continue with the local harvest and your own highlights when possible. Report that fallback; do not repeatedly redispatch or claim a successful CI preview. Save useful artifacts before their retention expires (currently seven days).

Harvest and review the source material

The workflow currently uploads notes and drafter logs, but not the full PR list or credits JSON. Generate those locally for the same range, without changing `CHANGELOG.md`:

python3 .github/scripts/changelog/generate.py \
  --repo "$notes_repo" --tag "$notes_head" --base "$notes_base" \
  --no-changelog-update \
  --section-out "$notes_dir/CHANGELOG-preview.md" \
  --draft-notes-out "$notes_dir/mechanical_notes.md" \
  --pr-list-out "$notes_dir/pr_list.txt" \
  --credits-out "$notes_dir/pr_credits.json"

The preview's section heading uses the head SHA and its commit date. Preserve that provenance; if relabeling it with the intended version, mark it as a draft and use only a confirmed planned date. The public `Full Changelog` link will not contain this version until the release-cut changelog PR is merged.

Read the complete PR list in batches. The CI drafter caps its prompt at 100,000 bytes, so its highlights can miss later entries in a large range. The harvester takes PR numbers from squash subjects in the Git range, not a merge-date search. If using bulk API metadata to save time, filter against that exact set and account for every PR; do not silently omit failed lookups. Use REST author login and profile URL for credits, including bo