docs(standards): formalize agent canary-ring/soak/promotion model + ADR (#869)

[don-petry]

Draft until the host-repo implementation PRs land — this standard references them.

Promotes ci-standards.md from the aspirational / manual (cut-release.sh-only) description to the automated, health-gated model now shipped for dev-lead v1.4.0:

• Ring table → canonical host-relative membership: next=host, ring0=other org-infra repo, ring1=named low-traffic consumers, stable=rest. Links canary-rings.json as the SoT.
• Rollout status → the built automation: canary-rollout.sh + 4h evaluate / dispatch-gated promote, the concrete soak gate (healthy ≥ ceil(baseline/7) AND failure-rate ≤ baseline, no floor), rollback, and the codified release-channel-tags ruleset.
• New ADR docs/initiatives/agent-canary-rings-adr.md — records the decision + rationale.

Blocking PRs (host repo petry-projects/.github-private): #878 (canary-rollout automation), #889 (ruleset codify), #880 (SHA-pin guardrail). Mark ready once those merge.

Closes #869. Refs #495, #499, #500, #501, #502, #868.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a new ADR outlining health-gated canary ring rollouts for agent releases, including one-ring-at-a-time promotion, rollback behavior, and host-relative ring membership semantics.
  • Updated CI standards to clarify ring/channel mapping, redefine ring membership and blast radius framing, expand rollout status details, and point to the machine-readable source of truth used by promotion automation.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6d0f68ce-9e16-4da4-b335-fb165d48f647

📥 Commits

Reviewing files that changed from the base of the PR and between 98cbb88 and 405e1ce.

📒 Files selected for processing (1)

• standards/ci-standards.md

---

📝 Walkthrough

Walkthrough

A new ADR documents the host-relative, health-gated canary ring release model for agent rollouts. standards/ci-standards.md is updated to reflect the ring membership model, promotion criteria, rollback behavior, and source-of-truth references.

Changes

Canary Ring Release Model Documentation

Layer / File(s)	Summary
New ADR: host-relative canary ring release strategy docs/initiatives/agent-canary-rings-adr.md	Adds title/metadata, context for the release strategy change, the decision for immutable releases with moving channel tags and host-relative concentric rings, the automated health-gated promotion workflow, the listed consequences, and links to host-repository operational documentation.
CI standards: ring membership table and rollout status standards/ci-standards.md	Rewrites the staged promotion rings table to define host-relative next and ring0 membership and blast radius, adds the standards/canary-rings.json source of truth, and expands rollout status for the dev-lead promotion flow, soak-gate criteria, rollback behavior, ruleset protection, and interim reusable handling.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• [Phase 2] Promote standards/ci-standards.md to the formalized ring/soak/promotion model (+ ADR) .github-private#869: The changes formalize the ring/soak/promotion model in standards/ci-standards.md and introduce the accompanying ADR, matching the issue’s scope.

Possibly related PRs

• petry-projects/.github#440: Both PRs update concentric-ring promotion semantics and the moving channel/stable tagging model in standards/ci-standards.md.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main docs change: formalizing the agent canary-ring, soak, and promotion model with a new ADR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/ci-standards-formalize-rings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Code Review

This pull request introduces an Architecture Decision Record (ADR) and updates the CI standards documentation to detail the new host-relative canary rings release strategy with health-gated promotion. The feedback highlights a documentation inconsistency, noting that the mentioned script scripts/apply-rulesets.sh does not currently support the release-channel-tags ruleset.

[don-petry]

Dev-Lead — fix-bot-comment (applied)

Changes committed and pushed.

[don-petry]

Dev-Lead — review-changes (no-changes)

No changes were needed for this PR.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[don-petry]

Dev-Lead — fix-bot-comment (no-changes)

Agent reasoning

Issues addressed: 0
- No actionable code findings in bot comment (API usage error, not code review)
Files changed: N/A
Skipped (informational): 0
```
The PR is clean: all CI checks pass, there are no code blockers, and the bot comment does not identify any code issues requiring remediation.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@standards/ci-standards.md`:
- Around line 100-113: The canary-ring description in this section is internally
contradictory: the table and host-relative explanation in the standards block,
including the references to next, ring0, and dev-lead, must be aligned to one
consistent self-host model. Update the adjacent prose so the definitions for
next and ring0 match the table and remove any wording that says ring 0 is the
reusable’s own self-host if next is the self-host ring; keep the
machine-readable source-of-truth note unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 3e03c46e-9235-4c60-bd5d-659969bcacd2

📥 Commits

Reviewing files that changed from the base of the PR and between 419c90f and 98cbb88.

📒 Files selected for processing (2)

• docs/initiatives/agent-canary-rings-adr.md
• standards/ci-standards.md

[don-petry]

Dev-Lead — fix-reviews (applied)

Changes committed and pushed.

[don-petry]

Note

@don-petry I reviewed this PR and no code changes were needed, but it still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews), so I cannot mark it done yet. I'll re-check automatically.
Next attempt after: 2026-06-24T12:25:26Z

[don-petry]

Dev-Lead — waiting on PR blockers (intent: fix-reviews)

PR: #520
No changes were committed, but the PR still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews). The retry cron will re-attempt automatically. Next attempt after: 2026-06-24T12:28:17Z

[don-petry]

Dev-Lead — waiting on PR blockers (intent: review-changes)

PR: #520
No changes were committed, but the PR still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews). The retry cron will re-attempt automatically. Next attempt after: 2026-06-24T13:03:02Z

[donpetry-bot]

Automated review — APPROVED ✓

Risk: LOW
Reviewed commit: 030a8213f1f31ed3fd922c7a6e8a57c9de67c7d8
Review mode: triage-approved (single reviewer)

Summary

Docs-only change (ADR + standards markdown; +92/-17 across 2 files) formalizing the host-relative, health-gated canary-ring release model for agent rollouts. Adds docs/initiatives/agent-canary-rings-adr.md and rewrites the rings table + 'Rollout status' section of standards/ci-standards.md. No code, config, auth, secrets, or CI-workflow logic touched. Triage's low-risk assessment confirmed.

Linked issue analysis

Closes #869 (host repo .github-private) — 'formalize the agent canary-ring/soak/promotion model'. Substantively addressed: the standard is promoted from the aspirational/manual description to the shipped automated model, and a decision-recording ADR is added. (closingIssuesReferences is empty in the API because #869 lives in the cross-repo host, which is expected.)

Findings

No blocking findings.

• The PR body's 'Draft until host-repo implementation PRs land' caveat is satisfied: the referenced automation now exists on .github-private@main — scripts/canary-rollout.sh, standards/canary-rings.json, .github/workflows/canary-rollout.yml, and scripts/apply-rulesets.sh all verified present. The PR is no longer a draft (isDraft=false).
• Prior CodeRabbit CHANGES_REQUESTED (internal next/ring0 contradiction, on superseded SHA 98cbb88) was resolved on the head SHA; CodeRabbit subsequently APPROVED the head commit (030a821).
• gemini-code-assist's earlier comment (apply-rulesets.sh lacked release-channel-tags support, on first SHA 73aa0cf) is moot: the head-SHA wording no longer references that script, and the script now exists on host main.
• mcp__github__run_secret_scanning unavailable in this run; not applicable to docs-only markdown, and the gitleaks CI secret scan passed.

CI status

All substantive checks green: Lint, ShellCheck, Secret scan (gitleaks), CodeQL, SonarCloud (Quality Gate passed), Agent Security Scan, AgentShield, CodeRabbit. Dependency-audit jobs SKIPPED (no manifest changes — expected). The only non-success entries are dev-lead/dispatch and dev-lead/ci-relay (CANCELLED) — the agent's own orchestration runs superseded by concurrency, not quality gates; a parallel dev-lead/dispatch ran SUCCESS. mergeStateStatus is BEHIND (needs rebase before merge; handled by auto-rebase, not a review blocker).

---

Reviewed automatically by the PR-review agent (single-reviewer mode: fable 5). Reply if you need a human review.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[don-petry]

Dev-Lead — fix-bot-comment (no-changes)

Agent reasoning

- ✓ 0 New issues
- ✓ 0 Accepted issues  
- ✓ 0 Security Hotspots
- ✓ 0% Coverage on New Code
- ✓ 0% Duplication on New Code
**Tier 1 Blockers:** Zero
- No CI checks with failure/cancelled/timed_out/action_required status
- No reviews with CHANGES_REQUESTED state
- All substantive checks passing (Lint, Secret scan, ShellCheck, SonarCloud, Agent Security Scan, AgentShield)
**Conclusion:** No changes required. The bot found zero actionable issues, and the PR has no blocking CI failures or change requests. The quality gate passed and all standards checks are green.