docs: contribution policy — CONTRIBUTING, PR template, changelog CI guards

[Anarchid]

Problem

agent-framework has no CONTRIBUTING.md, no PR template, and no changelog —
and no mechanism that would notice one was missing. @animalabs/agent-framework
is at 0.9.0 on npm, and the newest GitHub release in this repo is v0.3.0 from
April. Everything since is discoverable only by reading git log.

Three releases have shipped in the last two weeks, two of them minors carrying
real breaking changes, and none of them announced anywhere a consumer would
look:

• 0.8.0 renamed McplServerConfig.tokenProvider → accessProvider.
• 0.9.0 removed a public method from an exported class, changed a fleet
  default (tool results now spill at 5,000 chars), enforced MCPL 0.5
  deny-by-default before the policy handshake — which darkens un-migrated
  MCPL servers — and raised the chronicle floor to ^0.3.0, whose store
  format 0.2.x cannot reopen. That last one wants cold backups before
  upgrading a residence, and the only place it was ever written down is a
  release commit body.

A PR-side check alone can't carry the rule: across the ecosystem 52–85% of
commits on main land by direct push, and version bumps are release-time
maintainer actions by construction. The load-bearing layer is the tag-time
guard. This is the third rollout of the same policy, after connectome-host #49
and context-manager #51.

Changes

Ported from those two, adapted to this repo (build-before-test caveat,
stale-dist/ warning in the template):

• CONTRIBUTING.md — codifies existing practice rather than aspiration:
  merge commits only, comment-based review with run-the-branch transcripts,
  evidence-over-assertion test reporting, and AI attribution as the norm.
  Explicitly binds direct pushes and PRs, human and AI authors, identically.
• .github/PULL_REQUEST_TEMPLATE.md — Problem / Changes / Tests / Not
  verified, plus a changelog checkbox.
• .github/workflows/changelog.yml — soft PR check: touching src/
  without CHANGELOG.md fails, with a no-changelog label opt-out (label
  created).
• publish.yml — the publish job is now gated on the ref rather than the
  event, so a manual dispatch against a branch can no longer publish
  whatever version package.json happens to carry; a tag with no matching
  ## X.Y.Z section fails the release; and a new github-release job mirrors
  the tag's section into GitHub release notes, independent of npm publish so
  notes exist even when publish fails.
• scripts/release-changelog.mjs + a version hook in package.json —
  npm version <level> cuts Unreleased into ## X.Y.Z — YYYY-MM-DD
  pre-tag, so the tag and tarball carry it. Refuses an empty Unreleased, a
  duplicate section, and more than one Unreleased heading (a second one
  silently strands entries).
• CHANGELOG.md, watermarked at 0.7.3, with 0.7.4, 0.8.0 and 0.9.0
  written up in full.

That last point is deliberate. The earliest policy PRs held that the
enforcement PR should itself conform; this branch was cut 2026-07-27 and three
releases have shipped since. Landing an empty changelog would mean adding a
file already three releases behind main — the exact failure this PR exists
to prevent, committed by the PR that prevents it.

Entries are reconstructed from v0.7.3..v0.9.0 and grouped by the release
that carried them. Notes on the judgment calls:

• Breaking entries are audience-scoped, as the policy asks: consumers
  (the sendAfterInference removal, the spill default), MCPL servers (0.5
  deny-by-default, §7 removal), and dependency floors separately — the three
  audiences act on different things, and only the third needs the backup
  warning.
• 0.9.0's release commit already itemized its breaking surface and floors;
  that is carried over rather than re-derived.
• Review-response commits are folded into the entry for the feature they
  correct, not listed separately — the changelog describes released
  behavior, not the path to it.
• Test-only and refactor commits are omitted, per the policy's own rule about
  what needs an entry.

The package.json conflict from the rebase was resolved in favour of main's
--test-force-exit test script, with only the version hook added.

Tests

npm test: 560 tests, 560 pass, 0 fail, 0 skipped (70 suites). npm run build clean; tsc --noEmit: 0 errors. Green on this branch, ahead of the
539/538/1-skipped baseline the 0.9.0 release commit reported.

No src/ changes — this is docs, CI config, and one npm lifecycle hook — so
the suite is a regression check, not a demonstration. What was exercised
directly is the tooling this branch adds, against the real CHANGELOG.md:

• Tag guard simulated for all three sections: 0.7.4, 0.8.0, 0.9.0 —
  all match.
• Release-notes extraction, same awk as the workflow: 45 / 79 / 162 lines
  respectively, each starting at its first ### heading and stopping at the
  next ## — no bleed across section boundaries.
• scripts/release-changelog.mjs against a copy, package.json at 0.9.1:
  empty Unreleased → refused, exit 1; one entry added → cut Unreleased into '## 0.9.1 — 2026-08-07', exit 0, fresh empty Unreleased left above it;
  re-run → refused as duplicate, exit 1.
• Unreleased heading count: exactly 1.
• All three workflow files parse as YAML.

One reproduction note that cost time here and may cost a reviewer the same:
the workspace-symlinked membrane and context-manager checkouts had stale
dist/ (membrane's dated June, against 0.5.78 sources), which fails AF's
build on the retrying event type with 5 TS2678/TS2339 errors in
framework.ts. Rebuild those two first — it is a local-environment artifact,
not a branch or main defect, and CI installs from the registry so it cannot
hit this.

Not verified

• No agent was run. Nothing in this branch touches a runtime path, so no
  live inference, MCPL connection or store was exercised.
• The changelog.yml check has not run yet — this PR touches no src/ files,
  so it will pass trivially rather than exercising its failure path. The
  equivalent workflow was verified live on connectome-host test: add channel_publish fence coverage (home-default + foreign-reject) #49.
• The tag guard and github-release job cannot run until the next release and
  stay unexercised on real infrastructure until then, as on the previous two
  rollouts. The next npm version <level> && git push --follow-tags will be
  this repo's first GitHub release since v0.3.0.
• The 0.7.4–0.9.0 entries are reconstructed from commit messages and the
  measurements quoted in them, not re-measured. Incident details (token
  counts, outage durations, crash-cycle counts, dates) are as their authors
  reported them. Where a commit body and a release body disagreed on framing,
  I took the release body.
• I did not audit whether any consumer actually calls
  McplServerConnection.sendAfterInference; the changelog repeats chore(mcpl): drop the dead context/afterInference send surface (issue #39) #86's own
  14-tree grep rather than re-running it.

---

• CHANGELOG.md updated under ## Unreleased — or this change is
  internal-only / test-only / docs-only (apply the no-changelog label).

Docs-only by the letter of the check, but the file ships with three releases
written up rather than empty, per the self-conformance point above.

🤖 Generated with Claude Code