Skip to content

Prepare the 1.2.0 advisory release - #907

Merged
pengfei-threemoonslab merged 2 commits into
mainfrom
claude/release-1.2.0
Oct 1, 2026
Merged

pengfei-threemoonslab merged 2 commits into
mainfrom
claude/release-1.2.0

Conversation

@pengfei-threemoonslab

Copy link
Copy Markdown
Contributor

Prepares 1.2.0 on the advisory channel, per docs/release-runbook.md § Cutting the release (steps 1–3) and § The advisory release channel (step 1). It stops at "ready for the owner to review". No tag was pushed, no GitHub Release was created, the pypi environment was not approved, and nothing was uploaded anywhere.

Why this is a MINOR, not a patch

STABILITY.md § Versioning defines a minor as new features adhering to the contract. This cycle:

Channel: advisory, per docs/release-evidence-policy-decision.md § Amendment 5, as for 1.0.0 and 1.1.0. A tagged version's channel is frozen forever, so declaring 1.2.0 advisory means 1.2.0 can never carry a qualified claim.

What this changes

The release note (CHANGELOG.md). ## Unreleased is promoted to ## 1.2.0 - 2026-09-29. It is one line per change (33), with a framing paragraph, a ### Highlights block and the two pointers 1.1.0 carries. The subsection ### Application comparison without prior setup keeps its name, so the anchor README.md and docs/application-comparison.md link to still resolves. scripts/release_notes.py --tag v1.2.0 extracts it at 7,936 characters.

Claim discipline. The framing cites only measurements the entries themselves record:

It states the limits plainly:

  • diff --application reads OpenAI Agents SDK and Google ADK source wiring only;
  • it compares what it observes, not what runs;
  • what it cannot follow is a named gap;
  • reach is static, and read is bounded.

There is no "catches issues" framing.

The record. The full reviewed prose for all 33 entries moves verbatim to docs/changelog/1.2.0.md (new), linked from docs/INDEX.md.

Version-status reconciliation. In the record:

docs/application-comparison.md and README.md said "while that entry is under Unreleased, use a source build". They now say "new in 1.2.0; until 1.2.0 is published, use a source build", which stays true after publication. docs/engineering/permission-review-guidance.md's "are unreleased" becomes "had not shipped before 1.2.0".

STABILITY.md.

  • Title stamped · 1.2.0.
  • 18 Migration Note: Unreleased headings become Migration Note: 1.2.0; every heading has an explicit <a id> above it, so no inbound link breaks.
  • Six preamble paragraphs that opened "Unreleased" / "Also unreleased" now open "New in 1.2.0".
  • Note bodies that said verifier 0.21, capability diff 0.4 and contract v41 "are unreleased" now say they "had not shipped before 1.2.0".
  • "The unreleased tree" becomes "1.2.0", and one note that compared against an unshipped intermediate partial now compares against 1.1.0 and says the intermediate never shipped.

The general policy sentences about "unreleased main" and the historical migration-note-unreleased-* anchors are left alone.

Version sites.

File Change
pyproject.toml version = "1.2.0"
src/agents_shipgate/__init__.py __version__ = "1.2.0"
.well-known/agents-shipgate.json version only
docs/agent-contract-current.md In-tree runtime only
.claude-plugin/marketplace.json, plugins/claude-code/.claude-plugin/plugin.json, plugins/agents-shipgate/.codex-plugin/plugin.json plugin/manifest versions
llms.txt, docs/ai-search-summary.md source-tree runtime, keeping the "unreleased" qualifier
README.md, docs/quickstart.md "The source tree still reports version 1.2.0"
docs/design-partner-pilot-results.md Source tree: 1.2.0, with a clause saying only the label moved and the cells were not re-measured
generated schemas, docs/determinism-boundary.*, llms-full.txt regenerated (generate_schemas.py, build-llms-full.py)
docs/examples/capability-lock.v0.8.example.json cli_version
tests/golden/codex_boundary_result/*.json (8) tool.version
tests/test_v07_metadata_roundtrip.py the in-tree-runtime literal

Channel declaration. .github/release-channels.json gains "1.2.0": "advisory", and tests/test_release_channel.py's committed-declaration assertion moves with it.

What this deliberately does not change

  • No tag, no release, no publish.

  • No published-release pins (runbook step 8). These all stay at 1.1.0 until after publication:

    • LATEST_PUBLISHED_VERSION / LATEST_PUBLISHED_CONTRACT_VERSION;
    • .well-known's release_status.latest_release and package.github_action;
    • docs/agent-contract-current.md's "Latest release";
    • @v1.1.0 / ==1.1.0 pins.

    Moving them before the tag exists reproduces init writes an adopter workflow pinned to a tag that does not exist (56 days and counting) #506.

  • The two-phase labels stay. llms.txt, docs/ai-search-summary.md and the README/quickstart "not yet released" blocks keep their qualifiers until step 7.

  • No deprecated ID is removed. The IDs deprecated in 1.1.0 (docs/checks.md, STABILITY.md) become eligible for hard removal in 1.2.0 under § Versioning, but nothing requires it, and they stay readable.

  • No published run-of-record evidence and no GitHub issue text was edited.

Release checklist state

Runbook step State
1. Promote the CHANGELOG heading, split the prose done in this PR
2. Stamp STABILITY.md done in this PR
3a. pyproject.toml at the release version done in this PR
3b. .github/release-channels.json declares the channel done in this PR
3c. Release Engine Smoke (unqualified) not run: dispatch on the merged main commit
3d. Advisory Release Rehearsal not run: after the smoke, on that same commit
4. Push the tag owner decision
5. verify runs unattended after the tag
6. Approve the pypi environment gate owner only: the publication decision
7. Confirm the published release, run the fan-out checks after publication
8. Move the published-release constants and pins after publication

Tests

  • Locally, the full suite (-n 8) passes except three environmental cases that fail the same way on main on this workstation (a global git ignore of .claude/settings.local.json, and a long worktree path truncating one hint).
  • scripts/generate_schemas.py --check, scripts/verify_dependency_lock.py, ruff check . and ./shipgate doctor --config shipgate.yaml --json pass; doctor reports imported version 1.2.0 with no mismatches.
  • scripts/release_cadence.py --json reports the advisory line current (7 days since v1.1.0).

Needs the owner's decision

  1. The date on the heading is 2026-09-29. If the tag lands later, say so and I will re-date it before the smoke run. The release body is extracted from this commit.
  2. Whether the framing is the one you want in the release body. The framing paragraphs and ### Highlights say what the entries measure and nothing more.
  3. The deprecated IDs. Removing them is allowed from 1.2.0 on, but it is not done here. Keeping them costs nothing; removing them is a separate change.
  4. Before tagging, re-read docs/release-runbook.md § Deployment prerequisites. The recorded platform observations are dated 2026-09-09/10. Separately, the Protect main ruleset still requires suite (1)–suite (3) only. Name what a bound tool reaches in diff --application rows (#872) #906 split the suite into four shards, so suite (4) should be added there, and to the runbook's table once it is.

🤖 Generated with Claude Code

Prepares 1.2.0 on the advisory channel, per docs/release-runbook.md
§ Cutting the release (steps 1-3) and § The advisory release channel
(step 1). It stops at "ready for the owner to review": no tag, no GitHub
Release, no pypi approval, nothing uploaded.

- CHANGELOG.md: `## Unreleased` becomes `## 1.2.0 - 2026-09-29`, one line
  per change (33), with a framing paragraph, Highlights and the two
  pointers. It extracts at 7,936 characters.
- docs/changelog/1.2.0.md (new): the full reviewed prose, linked from
  docs/INDEX.md.
- Version-status reconciliation: entries and docs that called themselves
  unreleased now read true after publication. The application comparison
  result ships as schema `0.2`.
- STABILITY.md: title stamped · 1.2.0; 18 `Migration Note: Unreleased`
  headings become `Migration Note: 1.2.0`, anchors untouched; preamble and
  note sentences restated to stay true after publication.
- In-tree version sites: pyproject.toml, __version__, .well-known version,
  the three plugin manifests, llms.txt, docs/ai-search-summary.md, the
  source-tree version lines in README.md and docs/quickstart.md, the
  capability-lock example, the codex boundary goldens, the metadata
  roundtrip literal, and the pilot ledger's source-tree label. Schemas and
  llms-full.txt are regenerated.
- .github/release-channels.json declares "1.2.0": "advisory".

Published-release pins (runbook step 8) are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@pengfei-threemoonslab
pengfei-threemoonslab merged commit 7fc61ef into main Oct 1, 2026
13 checks passed
pengfei-threemoonslab added a commit that referenced this pull request Nov 8, 2026
… rewrite one (#1044 slice A) (#1116)

* fix(schemas): freeze published schema bytes; the generator refuses to rewrite one (#1044 slice A)

Three published schemas embedded the package version as a JSON-schema
default (`tool.version`), so every release-prep bump rewrote
docs/agent-handoff-schema.v9.json, docs/agent-result-schema.v3.json and
docs/agent-boundary-result-schema.v3.json under unchanged schema versions
(#847, #907), against docs/report-1-0-contract.md rule 3.

- AgentHandoffTool and AgentResultTool: `version` keeps the running version
  at runtime (default_factory) while the schema keeps the published
  "1.2.0" (json_schema_extra). Byte-identical output, proven under a
  simulated bump; a comment says successors emit no release-specific default.
- scripts/generate_schemas.py: one freeze mechanism. The published set is
  every docs/*-schema*.json a `v<version>` tag carries (from git, not a hand
  list) plus every pinned file, and, while the package version has no tag,
  every schema document on disk. When regenerating would change a published
  or pinned file, the generator writes nothing, exits 1 and names the
  successor-version route (and the locked-pydantic cause). `--check` also
  reports a published file that is missing, unpinned, changed, or different
  from the newest release that carried it. `--pin` adds missing pins and
  never moves one. Without tags (shallow clone, sdist) the published set
  falls back to the pin manifest, which CI keeps complete.
- scripts/published_schema_pins.json: 177 pins seeded from current bytes,
  the union of both former tables. agent-boundary-result v3 and verifier
  0.21 are recorded as re-frozen relative to v1.2.0 (#1088).
- tests: the two hand pin tables (test_effect_coverage
  _PUBLISHED_SCHEMA_SHA256, test_human_review_request FROZEN_CONTROL_SCHEMAS
  digests) now read the one manifest. The #561 and version-stamp exceptions
  are gone: both covered bytes no release shipped, and v1.0.0-v1.2.0
  published both files as now pinned. tests/test_published_schema_freeze.py
  runs the mechanism on this tree and shows each guard failing on its defect.
- Docs: report-1-0-contract rule 3, STABILITY, CONTRIBUTING, release-runbook
  step 3 (pin at the version bump), CHANGELOG.

Refs #1044

* docs(schemas): say which release published the frozen tool.version default

The test comment said v1.0.0 through v1.2.0 published agent-result v3
exactly as pinned; v1.0.0 and v1.1.0 each stamped its own version into
its `tool.version` default, so only v1.2.0 did. STABILITY.md,
docs/report-1-0-contract.md and the freeze test's docstring now say the
`1.2.0` default is the value v1.2.0 published, not the one these
documents were always published with.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant