[Phase 1] Generalize cut-release.sh + the release standard to cover non-agent reusables

[github-actions]

Story

As a OrganizationAdmin who cuts releases for first-party reusables,
I want use the same cut-release.sh tooling and a documented standard to version any first-party reusable, not only dev-lead/pr-review,
so that ci-failure-analyst (and future reusables) get release + channel tags through the existing, tested mechanism instead of bespoke per-workflow handling.

Acceptance Criteria

1. scripts/cut-release.sh valid_agent accepts ci-failure-analyst in addition to pr-review and dev-lead, and the usage/error strings list the expanded set.
2. tests/test_cut_release.bats is updated so the case currently asserting ci-failure-analyst is REJECTED instead asserts it is accepted, plus release_ref/channel_ref cases for it (e.g. ci-failure-analyst/v0.1.0, ci-failure-analyst/stable); the bats suite passes.
3. docs/release/versioning.md is extended to state the channel/version scheme applies to all first-party reusables (keeping <name>/stable + <name>/vMAJOR.MINOR.PATCH) and adds ci-failure-analyst to the 'what is versioned' table with its reusable + key scripts.
4. AGENTS.md section 'Release channel tags & the mutable-ref exception' is generalized so the documented exception and compliance guidance cover all first-party reusable channel tags (not only pr-review/dev-lead).
5. The chosen channel convention (one convention for all: <name>/stable + <name>/vX.Y.Z) is stated explicitly so downstream stories and the compliance test can rely on it.
6. shellcheck scripts/cut-release.sh passes and the script's source-guard still lets tests source the pure helpers without executing main.

Tasks / Subtasks

• Extend valid_agent to accept ci-failure-analyst and update usage/error messages. (AC: test issue from agent #1, feat: feature ideation framework — adversarial proposer/challenger/synthesizer #6)
  • Add ci-failure-analyst to the case in valid_agent (scripts/cut-release.sh).
  • Update the two expected: pr-review | dev-lead error strings and the header usage examples.
• Update the cut-release bats suite for the new agent. (AC: Go-live improvements for PR review agent #2)
  • In tests/test_cut_release.bats the 'unknown agent is rejected' case currently uses ci-failure-analyst — switch it to a genuinely-unknown name and add an acceptance case for ci-failure-analyst.
  • Add release_ref/channel_ref assertions for ci-failure-analyst.
  • Run bats tests/test_cut_release.bats to confirm green.
• Generalize the standard in versioning.md. (AC: Add @claude delegation, auto-merge, and rebase handling #3, feat: add Copilot engine support via REVIEW_ENGINE toggle #5)
  • Add a ci-failure-analyst row to the 'What is versioned' table (reusable .github/workflows/ci-failure-analyst-reusable.yml).
  • State the convention applies to all first-party reusables.
• Generalize the AGENTS.md release-channel exception wording. (AC: Optimize review: small-PR and incremental fast paths #4, feat: add Copilot engine support via REVIEW_ENGINE toggle #5)
  • Broaden the section from the pr-review/dev-lead pair to 'first-party reusable workflows' generally, preserving the ruleset/bypass caveats.

Dev Notes

• CRITICAL existing-test trap: tests/test_cut_release.bats line ~28 currently asserts valid_agent ci-failure-analyst RETURNS FAILURE ('unknown agent is rejected'). Extending the script WILL break that test unless it is updated in the same PR — do not just add the agent and leave the suite red.
• cut-release.sh is structured so pure helpers (valid_agent, validate_version, release_ref, channel_ref) are sourced by tests without running main (source-guard at the bottom). Preserve that structure; the helpers already build <agent>/vX.Y.Z and <agent>/<channel> generically, so only valid_agent needs the new name.
• Channel convention decision (discussion open question): adopt ONE convention for all reusables — <name>/stable + <name>/vMAJOR.MINOR.PATCH — matching what versioning.md already defines. Do not invent a per-tier scheme; surface that tradeoff to humans rather than guessing.
• This story is tooling + docs only; it does NOT cut any tag and does NOT touch the ruleset (those are admin/Phase-2). It unblocks story id 4.
• Testing standard: shell changes are covered by tests/test_cut_release.bats (bats) and shellcheck; run both. No GitHub mutations occur here.

Project Structure Notes

Edits existing files only: scripts/cut-release.sh, tests/test_cut_release.bats, docs/release/versioning.md, AGENTS.md. No new files.

References

• scripts/cut-release.sh (valid_agent)
• tests/test_cut_release.bats (valid_agent cases)
• docs/release/versioning.md (What is versioned)
• AGENTS.md (Release channel tags & the mutable-ref exception)
• docs/initiatives/agentic-release-strategy.md (epic Initiative: Safe Release Strategy for Agentic Workflows (versioning · rings · canary) #495)

Likely target surface

• scripts/cut-release.sh
• tests/test_cut_release.bats
• docs/release/versioning.md
• AGENTS.md

Story prepared by the BMAD Scrum Master (Bob) for epic #684. Status: ready-for-dev.

[don-petry]

Dev-Lead Implementation Plan

Issue: #686 — [Phase 1] Generalize cut-release.sh + the release standard to cover non-agent reusables

Scope

Fold ci-failure-analyst into the cut-release tooling + release standard as a first-party (this-repo) reusable, and generalize the docs so the channel/version scheme is stated as applying to all first-party reusables.

Current-state note

The repo has advanced past this Phase-1 issue's original assumptions: channels are now major-scoped (<name>/v<MAJOR>-<tier>, #1184) rather than the flat <name>/stable the issue text references, and #1159 already added ci-failure-analyst to valid_agent. I will complete the remaining gaps against the current scheme (not regress to the flat scheme) and flag this in the completion report.

Implementation Checklist

• scripts/cut-release.sh — add ci-failure-analyst to the usage-header <agent> list (this-repo agents) and to the unknown agent error string. (AC test issue from agent #1, feat: feature ideation framework — adversarial proposer/challenger/synthesizer #6)
• docs/release/versioning.md — add a ci-failure-analyst row to the 'What is versioned' table (reusable .github/workflows/ci-failure-analyst-reusable.yml); state the scheme applies to all first-party reusables; state the single channel convention explicitly. (AC Add @claude delegation, auto-merge, and rebase handling #3, feat: add Copilot engine support via REVIEW_ENGINE toggle #5)
• AGENTS.md — generalize 'Release channel tags & the mutable-ref exception' from the pr-review/dev-lead pair to first-party reusable channel tags generally, preserving ruleset/bypass caveats. (AC Optimize review: small-PR and incremental fast paths #4, feat: add Copilot engine support via REVIEW_ENGINE toggle #5)

Tests to Write

• tests/test_cut_release.bats — add release_ref case for ci-failure-analyst (ci-failure-analyst/v0.1.0) and channel_ref case (ci-failure-analyst/v0-stable, current major-scoped scheme). The valid_agent acceptance + agent_host_repo (this-repo) cases already exist (Decide: bring ci-failure-analyst under the versioned-release/canary model (currently SHA-pinned) #1159). (AC Go-live improvements for PR review agent #2)

Test Command

bats tests/test_cut_release.bats and bash .dev-lead/scripts/dev-lead-lint.sh (shellcheck)

[don-petry]

Dev-Lead: Implementation Complete

Plan Execution

• scripts/cut-release.sh — added ci-failure-analyst to the usage-header this-repo <agent> list and to the unknown agent error string (AC test issue from agent #1, feat: feature ideation framework — adversarial proposer/challenger/synthesizer #6).
• tests/test_cut_release.bats — added release_ref (ci-failure-analyst/v0.1.0) and channel_ref (ci-failure-analyst/v0-stable) cases (AC Go-live improvements for PR review agent #2).
• docs/release/versioning.md — added a ci-failure-analyst row to the 'What is versioned' table, reframed the intro + prose to cover all first-party reusables, and stated the single channel convention explicitly (AC Add @claude delegation, auto-merge, and rebase handling #3, feat: add Copilot engine support via REVIEW_ENGINE toggle #5).
• AGENTS.md — generalized 'Release channel tags & the mutable-ref exception' from the pr-review/dev-lead pair to first-party reusable channel tags generally, preserving the ruleset/bypass caveats (AC Optimize review: small-PR and incremental fast paths #4, feat: add Copilot engine support via REVIEW_ENGINE toggle #5).

Important reconciliation note

The repo has advanced past this Phase-1 issue's original assumptions:

• valid_agent already accepted ci-failure-analyst — landed earlier under Decide: bring ci-failure-analyst under the versioned-release/canary model (currently SHA-pinned) #1159, along with the valid_agent/agent_host_repo bats cases and the "unknown agent is rejected" case already using a genuinely-unknown name (totally-not-an-agent). So AC test issue from agent #1/Go-live improvements for PR review agent #2's valid_agent half was pre-satisfied; the remaining gaps were the usage/error strings, the release_ref/channel_ref tests, and the docs.
• Channels are now major-scoped (<name>/v<MAJOR>-<tier>, F2: cut-release.sh learns v<major>-<tier> channels [#657] #1184) rather than the flat <name>/stable the issue text references. I implemented against the current scheme rather than regressing it: the new bats case asserts ci-failure-analyst/v0-stable (not ci-failure-analyst/stable), and the docs state <name>/v<MAJOR>-<tier> as the one convention for all first-party reusables. This is the AC feat: add Copilot engine support via REVIEW_ENGINE toggle #5 "one convention for all" decision, applied consistently with the code as it stands today.

Test Results

$ bats tests/test_cut_release.bats
1..59
... (all ok) ...
BATS-GREEN

$ bats tests/test_cut_release_cross_repo.bats
1..15
... (all ok) ...
GREEN

$ shellcheck --severity=warning -x scripts/cut-release.sh
SHELLCHECK-OK

$ bash .dev-lead/scripts/dev-lead-lint.sh
  [lint] shellcheck on 80 file(s)...
  [lint] validating 4 agent profile(s)...
  [lint] validating .github/CODEOWNERS...
  [lint] all checks passed

# source-guard intact: `source scripts/cut-release.sh` defines helpers without running main()

Files Changed

• scripts/cut-release.sh: usage-header + error-string now list ci-failure-analyst (this-repo agent).
• tests/test_cut_release.bats: added release_ref/channel_ref cases for ci-failure-analyst.
• docs/release/versioning.md: ci-failure-analyst row + generalized intro/prose + explicit single convention.
• AGENTS.md: mutable-ref exception generalized to all first-party reusable channel tags.

Notes

• Scope respected: no tag is cut and the ruleset is untouched (both are admin/Phase-2). The AGENTS.md text documents that adding ci-failure-analyst/** to the release-channel-tags ruleset is an admin step that may lag the tooling/docs, and that the sanctioned-exception guidance applies regardless.
• ci-failure-analyst's reusable is fully inline (no dedicated scripts/), so its 'Key scripts' cell reflects that (inline gh api orchestration + the Claude Code action).
• The release_ref/channel_ref tests are green on the already-generic helpers; the behavioral change (valid_agent acceptance) was pre-landed by Decide: bring ci-failure-analyst under the versioned-release/canary model (currently SHA-pinned) #1159, so no separate red→green step was needed for that helper.

[don-petry]

PR #1213 has an unresolved review finding (not merge-ready yet). Copilot correctly flagged that this change leaves the docs internally inconsistent: docs/release/versioning.md and AGENTS.md describe major-scoped channels (<name>/v<MAJOR>-<tier>) in the intro but still describe the old <name>/stable scheme in the 'Tag scheme' / feature-ideation sections. This needs a doc-consistency fix on the PR branch (reconcile both docs to one channel-naming convention) before the 3 open threads resolve and it can merge. Flagging rather than force-resolving — the gate is correct. — Claude Code