[anth-volk]

Fixes #978

Same-Repository Draft PR Check

• This PR is a draft.
• This PR is from a branch in PolicyEngine/policyengine-sim-api, not a personal fork.

Changelog

• This PR adds a changelog fragment, changelog.d/<name>.<type>.md, whose type is breaking, added, changed, fixed or removed: changelog.d/978.added.md and changelog.d/978.changed.md.

Summary

Moves the changelog from the shared changelog_entry.yaml to Towncrier fragments, requires a valid fragment on every pull request, and builds CHANGELOG.md at each deploy, as policyengine-api does, without the two gaps in policyengine-api's check.

Fragments and the check (rule sim.process.changelog-fragment)

• towncrier.toml at the root (the root has no pyproject.toml) with policyengine-api's five types: breaking, added, changed, fixed, removed. Its ignore list makes Towncrier stop at any unreadable file in changelog.d/ instead of skipping it.

• .github/scripts/changelog_fragments.py holds the one definition of a fragment, which the check and the version bump both use. A fragment is a non-empty UTF-8 file directly in changelog.d/, named <name>.<type>.md, with a type towncrier.toml lists. It reads the directory and the types from towncrier.toml, and refuses to run if those types differ from the bump table.

• The new check-changelog job in pr.yml runs .github/scripts/check-changelog-fragment.sh on the merged result against github.event.pull_request.base.sha. It has the stack condition and is in CI complete's needs, so it becomes a merge requirement through the existing required check. It fails unless the pull request itself adds a fragment and every file in changelog.d/ is one. policyengine-api's check counts any file anywhere under changelog.d/, so:

  • it passed #4084's changelog.d/added/4083.md, which its release couldn't read (this PR's proof fixture);
  • it passes a pull request with no fragment while main has pending ones.

  Both now fail here, as do unknown types, other names and empty files. Towncrier itself silently skips subfolder files and unknown types, and drops empty fragments; I checked this with 26.9.0.

Version and history

• VERSION (new, 0.1.0) is the repository's release version. The bump writes it, and the build passes it to Towncrier's title. 0.1.0 is the version every package already declares, nothing has ever published another, and a 0.x version claims no API stability.
• The bump mirrors policyengine-api's bump_version.py: breaking raises the major version, added or removed the minor, changed or fixed the patch. The largest wins.
• The 63 entries of changelog_entry.yaml (17 added, 28 changed, 18 fixed) are now the 0.1.0 section of CHANGELOG.md, word for word and in order, and the YAML file is removed.
  • I copied the file's lines rather than YAML-parsing them, because two entries parse as mappings (an unquoted : ).
  • The locked Towncrier rendered the section from one temporary fragment per entry, so it has the format later releases will have. A test pins a SHA-256 of the entries.
  • A section, not 63 fragments: those changes already deployed when their pull requests merged. As fragments, the first release after this PR would have listed months of deployed work under its own version and date, and bumped the version for it.

Release at each deploy (rule sim.deploy.release-commit-deploys-once)

• simulation-deploy.yml gains a versioning job, which runs for a push to main whose head commit isn't the release commit:
  1. It creates a GitHub App token (APP_ID, APP_PRIVATE_KEY, permission-contents: write) and checks out with it.
  2. It runs .github/scripts/build-changelog.sh: the bump, then Towncrier from .github/towncrier, which removes the fragments.
  3. It runs .github/scripts/commit-release.sh, which commits only VERSION, CHANGELOG.md and the fragment removals as Update PolicyEngine simulation API, and pushes the commit to main.
• The App's push starts the workflow again. beta (and so prod) and summary run only for that release commit or a manual dispatch, and versioning runs for neither. So each merge deploys once, and the release commit starts no further release.
• publish-clients.yml publishes only after the release commit's run. The workflow-level concurrency group simulation-deploy-main is unchanged, and workflow_dispatch (with its inputs) still deploys, without a release.
• When two merges land close together, the later merge's run waits in the concurrency group and releases both merges' fragments. If the earlier run's push finds main already moved on, commit-release.sh says so and exits 0 instead of failing.
• Towncrier 26.9.0 is locked in a project of its own, .github/towncrier (pyproject.toml and uv.lock, package = false). make update relocks it, check-uv-locks.sh checks it, and it installs with uv run --frozen, so the locked-installs and uv-version rules cover it with no exception.
• make changelog builds a release locally. make changelog-draft prints the next section and changes nothing.

Automated pull requests now add their own fragments, since the new check would fail them otherwise:

• the daily dependency update adds changelog.d/update-dependencies.changed.md, with fixed text, so its same-files comparison still works;
• the policyengine.py update adds changelog.d/update-policyengine-<version>.changed.md.

Docs:

• github-prs.md gains a "Changelog Fragments" section, and its PR checklist a fragment step.
• AGENTS.md's changelog sentence and PR steps are updated, the PR template gains a Changelog checkbox, and ci-workflows.md notes that only versioning pushes to main.
• dependencies.md lists .github/towncrier, and README.md and CONTRIBUTING.md describe the release flow.
• rules.md and the AGENTS.md rules block are re-rendered.

Environment variables and secrets

Variable	Read by	Provider	Wiring
APP_ID	versioning: create-github-app-token app-id	GitHub Actions organization secret, visible to this repository	${{ secrets.APP_ID }} in the step's with:, in a push-triggered job of this repository
APP_PRIVATE_KEY	versioning: create-github-app-token private-key	GitHub Actions organization secret, visible to this repository	${{ secrets.APP_PRIVATE_KEY }}, same step
App token	versioning: checkout token:, then git push in commit-release.sh	output of actions/create-github-app-token@v3	steps.app-token.outputs.token goes to checkout, which stores it as git's credential (the same pattern as update-dependencies.yml)
RELEASE_COMMIT_MESSAGE	commit-release.sh	workflow literal	step env:; the tests check that it matches every deploy condition and publish-clients.yml
BASE_SHA	check-changelog-fragment.sh	pull_request event payload (github.event.pull_request.base.sha)	step env:; the checkout has fetch-depth: 0
github.event.head_commit.message	job ifs in simulation-deploy.yml	push event payload	expression only
github.event.workflow_run.head_commit.message	publish-clients.yml job if	workflow_run event payload	expression only

The existing beta/prod secrets (secrets: inherit) are unchanged. build-changelog.sh and changelog_fragments.py read no environment variables.

Ruleset 3680274: its bypass list includes Integration 2165692 with bypass_mode: always.

• gh api apps/policyengine returns id 2165692.
• The pull requests that update-dependencies.yml and check-policyengine-updates.yml open with tokens from APP_ID/APP_PRIVATE_KEY are authored by app/policyengine. That indicates the App behind APP_ID is 2165692; I didn't read the secret's value.
• policyengine-api's ruleset has the same rule types and the same bypass integration, and its Update PolicyEngine API commits on master are pushed by policyengine[bot], which starts its push runs.

Unverified until the first merge: that this App push to this repository's main succeeds, and that it starts the deploy run. The first proof is this PR's own merge: it should produce a 0.2.0 release commit, and that commit's run should deploy. If the push is refused, versioning fails and nothing deploys; dispatching simulation-deploy.yml still deploys main.

Testing

Each behaviour has a failing-test commit followed by the change. I re-ran each pair's tests at both commits:

Behaviour	Red commit	Green commit
Fragment check	b58238e: 37 failed	9784eee: 37 passed
Version bump and build	f39fe3e: 28 failed	3ef2841: 28 passed
History move	e3f294a: 5 failed	08d3ef9: 5 passed
Release and deploy workflow, pr.yml wiring	58d3e5f: 20 failed, 6 passed	505b72b: 26 passed
Automated pull request fragments	2bf07c1: 1 failed per project	2bf643c: 2 passed per project

In the workflow row, the 6 that pass at the red commit are cases the old workflow also satisfies: the release commit and a dispatch deploy, and publication follows a successful push.

• projects/policyengine-simulation-entry: uv run --frozen pytest tests/, 840 passed.
• projects/policyengine-simulation-executor: test_ci_complete_gate.py, test_policyengine_package_update_scripts.py and test_modal_scripts.py, 134 passed.
• ruff 0.15.22: ruff format --check projects/*/src libs/*/src and ruff check . pass, and the changed Python files are formatted.
• python scripts/run_quality_guards.py, python -m scripts.rules guard --base-ref origin/main and the rules-tool tests (263) pass. python -m scripts.rules render leaves no diff.
• .github/scripts/check-uv-locks.sh passes for all 9 locks (after ./scripts/generate-clients.sh), and shellcheck 0.11.0 is clean on the 5 changed scripts.
• BASE_SHA=origin/main .github/scripts/check-changelog-fragment.sh accepts this branch's two fragments.
• make changelog-draft prints the 0.2.0 section below.
• I rehearsed the release end to end in a scratch clone, with real Towncrier and a push to a local bare remote. It produced one github-actions[bot] commit, Update PolicyEngine simulation API, holding VERSION 0.2.0, the new CHANGELOG.md section above 0.1.0, and the two fragment removals.
• Pyright covers only src, which this PR doesn't touch.

Draft of the first release:

## [0.2.0] - 2026-10-28

### Added

- Added changelog fragments: every pull request adds one or more files `changelog.d/<name>.<type>.md`, ...

### Changed

- A merge to `main` no longer deploys by itself. ...

Notes for reviewers

• Merging this PR changes what deploys: its own merge runs only versioning, and the release commit deploys.
• The 11 open PRs that edit changelog_entry.yaml will conflict. Each needs to drop that edit and add a fragment.
• A rebase merge whose last commit message is exactly Update PolicyEngine simulation API (GitHub compares case-insensitively) would deploy without a release. Squash merges add (#N) and merge commits start with Merge pull request.
• A policyengine.py update branch left by a run before this change, then reopened as a PR, has no fragment and would need one added.

🤖 Generated with Claude Code