feat(release): MVP — release-please + v1.0.0 manifest + hybrid pin guidance

[muntianus]

Summary

Closes the audit follow-up tracked in #27's PR body. Migrates this repo from "designed-but-not-implemented" to "live release pipeline + hand-authored v1.0.0 contract".

This PR ships:

1. Design doc — docs/release/v1-strategy.md (commit 1).
2. MVP implementation (commit 2): release-please workflow + v1.0.0 manifest + hand-authored CHANGELOG entry + consumer dependabot example + AGENTS.md guidance bump.

What lands

Release automation:

• .github/workflows/release-please.yml — opens release PRs from Conventional Commits, cuts tag + GitHub Release on merge, re-points floating v1 major tag in lockstep. googleapis/release-please-action SHA-pinned with # v4.4.0 comment per the hybrid pattern this repo now enforces.
• version.txt + .release-please-manifest.json + release-please-config.json — release-type: simple source of truth. No language package manifests to bump in a workflows-only repo.

Hand-authored v1.0.0 contract:

• CHANGELOG.md documents the public input/secret/output contract of every reusable workflow in this release: reusable-ci-go, reusable-ci-node, reusable-deploy-vps, reusable-security-gate, openapi-sync, claude.yml. This is the document downstream consumers cite when judging "is this bump safe for me?".

Consumer dependabot template:

• docs/release/consumer-dependabot.example.yml — drop-in dependabot.yml for any of the 5 consumer repos. Grouped under the muntianus-workflows pattern so 5 weekly PRs collapse to 1.

AGENTS.md updates:

• Rule 3 (Reuse over fork) — switched from bare SHA pinning to the hybrid pattern @<sha> # v1.0.0, with tj-actions/changed-files Mar-2025 as the reference incident.
• Rule 4 (NEW) — Conventional Commits requirement for changes to this repo; explicit definition of "breaking change" for a reusable workflow (inputs/secrets/outputs/permissions/observable side-effects).

Out-of-band steps after merge (manual, no PR needed)

1. Cut the actual v1.0.0 tag and GitHub Release manually — git tag v1.0.0 && git push origin v1.0.0 plus a Release with the CHANGELOG body. One-time bootstrap; release-please takes over from v1.0.1+.
2. Push the floating v1 tag pointing at the same SHA — git tag -f v1 v1.0.0 && git push -f origin v1.
3. Configure a ruleset on v* in Settings → Rules → Rulesets: Restrict creation/update/deletion, bypass = repo admins only. UI-only.
4. Open 5 consumer PRs swapping current @<sha> to @<sha> # v1.0.0 and dropping in .github/dependabot.yml per the example file.

Test plan for this PR

• release-please.yml lints under actionlint (action SHAs verified)
• version.txt + .release-please-manifest.json match (1.0.0)
• CHANGELOG.md documents every workflow currently in this repo
• AGENTS.md rules renumbered cleanly (1→9, was 1→8)
• Reviewer: confirm the workflow contracts in CHANGELOG match each workflow's actual inputs:/secrets: block (I worked from the files in .github/workflows/; if I missed an input default, flag it)
• Reviewer: confirm the manual bootstrap steps above (or veto and bump straight via release-please first run)

Follow-up PRs (separate)

Tracked in the design doc:

• 5 consumer migration PRs (polymarket-arb, launchgate, benchmark-apps, architecture, chaos-scenarios) — @<sha> → @<sha> # v1.0.0 + dependabot.yml.

https://claude.ai/code/session_01NXqUreamtsrtqYAVBURZY4

[gemini-code-assist]

Code Review

This pull request introduces a release strategy document proposing a hybrid pinning approach for reusable workflows to balance security and maintainability. The review feedback correctly identifies three key issues in the proposed configurations: the release-please workflow is missing a checkout step, the tag ruleset bypass list must include GitHub Actions to allow automated tag updates, and the Dependabot group pattern needs to be adjusted to match the repository name correctly.

[gemini-code-assist]

The workflow steps do not clone the repository. Without a cloned repository, the runner's workspace is empty, and the subsequent git tag and git push commands in the Move floating v1 tag step will fail with a not a git repository error.

Please add the actions/checkout step at the beginning of the job, using a SHA-pinned reference to adhere to the repository's security guidelines.

Suggested change

	steps:
	- uses: googleapis/release-please-action@db8f2c60ee802b3748b512940dde88eabd7b7e01 # v4.4.0
	steps:
	- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
	- uses: googleapis/release-please-action@db8f2c60ee802b3748b512940dde88eabd7b7e01 # v4.4.0

[gemini-code-assist]

Since the release-please workflow runs automatically in CI and needs to force-push/update the floating v1 tag (which matches the v* pattern), restricting the bypass list to repository admins only will cause the automated workflow to fail when attempting to push the tag.

You should update the bypass list to also allow the GitHub Actions bypass actor (or the specific integration/app used for the workflow) to bypass the ruleset for tag updates.

Suggested change

	- Bypass list: repository admins only, with audit logging.
	- Bypass list: repository admins and GitHub Actions (for tag updates), with audit logging.

[gemini-code-assist]

In Dependabot, the dependency name for a reusable workflow is the repository name (e.g., muntianus/.github), not the full path to the workflow file. Therefore, the pattern muntianus/.github/* will not match the dependency name because of the trailing slash and wildcard.

To have the group correctly match and group updates for these workflows, the pattern should be updated to muntianus/.github.

Suggested change

	patterns:
	- muntianus/.github/*
	patterns:
	- muntianus/.github