Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions .github/workflows/initiative-driver.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
name: Initiative Driver

# Dependency-aware label dispatcher. Releases an initiative epic's sub-issues to
# the dev-lead agent (by applying the `dev-lead` label) as their "blocked by"
# dependencies close — turning the per-item agent into a coordinated, ordered
# delivery of a whole initiative.
#
# Mechanics, gates, and the PAT requirement are documented in
# scripts/initiative-driver.sh and docs/initiatives/agentic-release-strategy-orchestration.md.
#
# SAFETY: the driver no-ops unless the epic carries the `initiative:auto` label,
# so Phase 1 stays human-driven. Flip it on for Phase 2 by adding that label to
# the epic (#495). Per-issue `dev-lead:hands-off` / `initiative:hold` are never
# released.

on:
issues:
types: [closed] # a close may unblock successors — re-evaluate the DAG
schedule:
- cron: "23 */6 * * *" # safety net for missed close events
workflow_dispatch:
inputs:
epic:
description: "Epic issue number to drive"
required: false
default: "495"
dry_run:
description: "Log decisions but do not apply labels"
required: false
default: "false"
max_in_flight:
description: "Max sub-issues released at once"
required: false
default: "2"

permissions:
contents: read # actions/checkout; all issue mutations use the PAT (GH_TOKEN)

concurrency:
group: initiative-driver-${{ github.event.inputs.epic || '495' }}
cancel-in-progress: false

env:
REPO: ${{ github.repository }}
EPIC: ${{ github.event.inputs.epic || '495' }}
CLOSED_ISSUE: ${{ github.event.issue.number }}
DRY_RUN: ${{ github.event.inputs.dry_run || 'false' }}
MAX_IN_FLIGHT: ${{ github.event.inputs.max_in_flight || '2' }}
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

jobs:
drive:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Checkout agent repo
uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
with:
persist-credentials: false

- name: Guard — PAT present
# PAT required: a label applied with GITHUB_TOKEN does NOT trigger dev-lead.yml.
env:
GH_TOKEN: ${{ secrets.GH_PAT_WORKFLOWS }}
run: |
if [ -z "${GH_TOKEN}" ]; then
echo "::error::GH_PAT_WORKFLOWS is required — a label applied with GITHUB_TOKEN will not trigger dev-lead."
exit 1
fi

- name: Drive initiative
env:
GH_TOKEN: ${{ secrets.GH_PAT_WORKFLOWS }}
run: bash scripts/initiative-driver.sh
2 changes: 1 addition & 1 deletion .github/workflows/lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ jobs:
run: sudo apt-get install -y bats

- name: Run tests
run: bats tests/fleet_report.bats tests/token_report.bats tests/model_pricing.bats tests/test_review_cycle.bats tests/test_ci_status.bats tests/test_verify_auth_scopes.bats
run: bats tests/fleet_report.bats tests/token_report.bats tests/model_pricing.bats tests/test_review_cycle.bats tests/test_ci_status.bats tests/test_verify_auth_scopes.bats tests/test_initiative_driver.bats

validate-agent-profiles:
runs-on: ubuntu-latest
Expand Down
102 changes: 102 additions & 0 deletions docs/initiatives/agentic-release-strategy-orchestration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
# Delivering the Release-Strategy initiative agentically

Companion to `agentic-release-strategy.md` (not yet published). This doc explains how the
10 child issues of epic #495 are delivered by the existing **per-item dev-lead agent** in dependency
order — without changing the agent itself.

## The problem this solves

Dev-lead is purely reactive and **per-item**: it works one issue only when the `dev-lead` label is
applied (`issues: [labeled]`), opens a PR that `Closes #N`, and drives that PR to merge. It has **no
ordering or dependency awareness** — labelling all 10 issues at once runs them in parallel and produces
PRs racing to merge with no regard for "#496 must land before #497".

**Reframe:** coordinating an initiative = deciding *when* the `dev-lead` label is applied to each
ready issue. That decision is what `scripts/initiative-driver.sh` + `.github/workflows/initiative-driver.yml`
automate.

## How the driver works

```
dev-lead merges a PR ──► "Closes #N" closes issue #N
│
▼
initiative-driver (on: issues:[closed] + safety-net cron + workflow_dispatch)
│ gate: epic carries `initiative:auto`? ── no ─► no-op (human-driven)
│ for each OPEN sub-issue of the epic:
│ • all `blocked_by` deps CLOSED?
│ • not `dev-lead:hands-off` / `initiative:hold`?
│ • in-flight < MAX_IN_FLIGHT?
▼
apply `dev-lead` label ──► dev-lead picks up the next ready issue
```

- **Native dependencies.** Edges are GitHub "blocked by" relationships (set on #496–#506), visible in
the issue UI and queried via `…/issues/{n}/dependencies/blocked_by`.
- **Event-driven, self-propelling.** A merge closes an issue, which fires the driver, which releases
the now-unblocked successors. The cron (`23 */6 * * *`) is only a backstop for missed events.
- **Bounded.** `MAX_IN_FLIGHT` (default 2) caps how many sub-issues run at once — controlling parallel
token cost and blast radius. Per-issue concurrency lanes in dev-lead keep concurrent items isolated.

### The PAT requirement (important)

A label applied with the default `GITHUB_TOKEN` does **not** start a new workflow run (GitHub
loop-prevention — the same mechanism behind pr-review #463). The driver therefore applies the
`dev-lead` label using **`GH_PAT_WORKFLOWS`**, so the resulting `issues:[labeled]` event actually
triggers dev-lead. The workflow fails fast if that PAT is absent.

### Safety gates

| Gate | Effect |
|---|---|
| `initiative:auto` on the **epic** | Master switch. Absent ⇒ driver no-ops. Phase 1 stays human-driven until you add it. |
| `dev-lead:hands-off` on an **issue** | Never released (needs a human — e.g. PRs that modify dev-lead/pr-review themselves). |
| `initiative:hold` on an **issue** | Never released (temporary human hold). |
| `MAX_IN_FLIGHT` | Upper bound on concurrently-released sub-issues. |

## The dependency DAG (epic #495)

```
#496 ──┬─► #497 ──┬─► #498
│ ├─► #499 ──► #500 ──┐
└─► #505 └─► #506 ──────────►#501 ──► #502 ──► #503
#505 ───────────┘
```

| Wave | Issues | Gated on |
|---|---|---|
| 1 | #496 cut `vX.Y.Z` + create `stable` | — |
| 2 | #497 pin callers · #505 tag protection | #496 |
| 3 | #498 runbook · #499 next/ring tags · #506 caller-ref integrity | #497 |
| 4 | #500 rings | #499 |
| 5 | #501 promotion workflow | #500, #505, #506 |
| 6 | #502 rollback + observability | #501 |
| 7 | #503 SC2 game-day | #502 |

## Bootstrap order: human-driven → agent-driven

This initiative modifies dev-lead/pr-review themselves, so the rollout order is also a **safety
bootstrap**, not just a technical dependency:

- **Phase 1 (#496, #497, #505, #498) — human-in-the-loop.** Until `@stable` exists and production duty
is pinned to it (#497), there is no known-good fallback; letting the agent autonomously merge changes
that could brick itself is exactly the failure mode we're removing. Leave `initiative:auto` **off**;
apply the `dev-lead` label by hand, wave by wave (or merge by hand). Issues that edit
`dev-lead.yml`/`pr-review.yml` carry `dev-lead:hands-off` and require human merge regardless.
- **Phase 2 (#499 onward) — agent-driven.** Once #497 lands, production review/dev duty runs `@stable`,
so a broken `main`/`next` can no longer block its own fix. **Now** add `initiative:auto` to the epic
and let the driver run the rest.

## Operating the driver (runbook)

- **Dry-run / preview** what would be released:
`gh workflow run initiative-driver.yml -f dry_run=true` (or run the script with `DRY_RUN=true`).
- **Arm Phase 2:** `gh issue edit 495 --add-label initiative:auto`.
- **Pause one issue:** add `initiative:hold`; **hand back to a human:** add `dev-lead:hands-off`.
- **Throttle:** `gh workflow run initiative-driver.yml -f max_in_flight=1`.
- **Disarm:** remove `initiative:auto` from the epic — in-flight items finish; nothing new is released.

## Follow-ups (not in this scaffold)

- A bats test that mocks `gh` to assert the gate / blocker / cap logic.
- Generalize `EPIC` beyond the hard-coded `495` default if a second initiative adopts the driver.
165 changes: 165 additions & 0 deletions scripts/initiative-driver.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
#!/usr/bin/env bash
#
# initiative-driver.sh — dependency-aware label dispatcher for initiative epics.
#
# Turns an epic's sub-issue dependency graph (native GitHub "blocked by"
# relationships) into dev-lead pickups: it applies the `dev-lead` label to each
# OPEN sub-issue whose blockers are ALL closed, bounded by a max-in-flight cap.
# The dev-lead agent triggers on issues:[labeled]; this script is the only thing
# that decides WHEN that label goes on, so the per-item agent stays unchanged.
#
# Event-driven chain: dev-lead merges a PR -> "Closes #N" closes the issue ->
# this driver (on issues:[closed]) re-evaluates the DAG -> labels the now-ready
# successors. The schedule cron is only a safety net for missed close events.
#
# IMPORTANT — the trigger requires a PAT, not GITHUB_TOKEN:
# GitHub does not start new workflow runs from events created by the default
# GITHUB_TOKEN (loop prevention). The `dev-lead` label MUST be applied with a
# PAT (GH_PAT_WORKFLOWS) or the resulting issues:[labeled] event will NOT
# trigger dev-lead.yml. (Same class of bug as pr-review #463.)
#
# Safety gates:
# - The epic must carry GATE_LABEL (default: initiative:auto). Without it the
# driver no-ops, so Phase 1 stays human-driven until you opt in.
# - Issues carrying HANDS_OFF_LABEL (dev-lead:hands-off) or HOLD_LABEL
# (initiative:hold) are never released — they need a human.
# - MAX_IN_FLIGHT bounds how many sub-issues run at once (cost / blast radius).
#
# Env:
# REPO owner/repo (default: petry-projects/.github-private)
# EPIC epic issue number (required)
# CLOSED_ISSUE issue number from an issues:closed event (optional; the run
# exits early if it is not one of the epic's sub-issues)
# DEV_LEAD_LABEL label that triggers dev-lead (default: dev-lead)
# GATE_LABEL opt-in label on the epic (default: initiative:auto)
# HANDS_OFF_LABEL never-release label (default: dev-lead:hands-off)
# HOLD_LABEL never-release label (default: initiative:hold)
# MAX_IN_FLIGHT cap on concurrently-released sub-issues (default: 2)
# DRY_RUN "true" to log decisions without labeling (default: false)
#
set -euo pipefail

REPO="${REPO:-petry-projects/.github-private}"
EPIC="${EPIC:?EPIC issue number required}"
CLOSED_ISSUE="${CLOSED_ISSUE:-}"
DEV_LEAD_LABEL="${DEV_LEAD_LABEL:-dev-lead}"
GATE_LABEL="${GATE_LABEL:-initiative:auto}"
HANDS_OFF_LABEL="${HANDS_OFF_LABEL:-dev-lead:hands-off}"
HOLD_LABEL="${HOLD_LABEL:-initiative:hold}"
MAX_IN_FLIGHT="${MAX_IN_FLIGHT:-2}"
DRY_RUN="${DRY_RUN:-false}"
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

# Validate and normalize inputs before they reach arithmetic or API paths.
[[ "$EPIC" =~ ^[0-9]+$ ]] || { echo "::error::EPIC must be a positive integer, got: '$EPIC'"; exit 1; }
[[ "$MAX_IN_FLIGHT" =~ ^[0-9]+$ ]] || { echo "::error::MAX_IN_FLIGHT must be a non-negative integer, got: '$MAX_IN_FLIGHT'"; exit 1; }
if [[ -n "$CLOSED_ISSUE" ]] && ! [[ "$CLOSED_ISSUE" =~ ^[0-9]+$ ]]; then
echo "::warning::CLOSED_ISSUE is not a valid issue number ('$CLOSED_ISSUE') — treating as unset."
CLOSED_ISSUE=""
fi
DRY_RUN="${DRY_RUN,,}"
case "$DRY_RUN" in
true|1|yes) DRY_RUN=true ;;
false|0|no) DRY_RUN=false ;;
*) echo "::error::DRY_RUN must be true or false, got: '$DRY_RUN'"; exit 1 ;;
esac
readonly REPO EPIC CLOSED_ISSUE DEV_LEAD_LABEL GATE_LABEL HANDS_OFF_LABEL HOLD_LABEL MAX_IN_FLIGHT DRY_RUN

log() { printf '%s\n' "$*"; }

# has_label <newline-separated-labels> <name> — pure-bash exact-line match; no subprocesses.
has_label() { [[ $'\n'"${1}"$'\n' == *$'\n'"${2}"$'\n'* ]]; }

# labels_of <issue-number> — newline-separated label names.
labels_of() {
gh api "repos/$REPO/issues/$1" --jq '.labels[].name'
}

# ── gate: the epic must opt in ────────────────────────────────────────────────
epic_labels="$(labels_of "$EPIC")"
if ! has_label "$epic_labels" "$GATE_LABEL"; then
Comment thread
don-petry marked this conversation as resolved.
Resolved
log "Gate '$GATE_LABEL' not on epic #$EPIC — no-op (Phase-1 human-driven). Add the label to activate."
exit 0
fi

# ── enumerate sub-issues (all states) ─────────────────────────────────────────
all_children_raw="$(gh api --paginate "repos/$REPO/issues/$EPIC/sub_issues" --jq '.[].number')"
if [[ -z "$all_children_raw" ]]; then
all_children=()
else
mapfile -t all_children <<< "$all_children_raw"
fi
if [[ "${#all_children[@]}" -eq 0 ]]; then
log "Epic #$EPIC has no sub-issues — nothing to drive."
exit 0
fi

# ── on a close event, only act if the closed issue belongs to this epic ───────
if [[ -n "$CLOSED_ISSUE" ]]; then
in_epic=false
for n in "${all_children[@]}"; do
[[ "$n" = "$CLOSED_ISSUE" ]] && in_epic=true && break
done
if [[ "$in_epic" != true ]]; then
log "Closed issue #$CLOSED_ISSUE is not a sub-issue of epic #$EPIC — no-op."
exit 0
fi
fi
Comment thread
don-petry marked this conversation as resolved.
Resolved

# ── count in-flight (released but not yet closed) ─────────────────────────────
declare -A released
in_flight=0
open_children_raw="$(gh api --paginate "repos/$REPO/issues/$EPIC/sub_issues" \
--jq '.[] | select(.state=="open") | .number')"
if [[ -z "$open_children_raw" ]]; then
open_children=()
else
mapfile -t open_children <<< "$open_children_raw"
fi
for n in "${open_children[@]}"; do
n_labels="$(labels_of "$n")"
if has_label "$n_labels" "$DEV_LEAD_LABEL"; then
released[$n]=1
in_flight=$((in_flight + 1))
fi
done
log "Epic #$EPIC: ${#open_children[@]} open sub-issue(s); in-flight=$in_flight; cap=$MAX_IN_FLIGHT."

# ── release ready sub-issues up to the cap ────────────────────────────────────
slots=$((MAX_IN_FLIGHT - in_flight))
[[ "$slots" -lt 0 ]] && slots=0
released_now=0

for n in "${open_children[@]}"; do
[[ "$slots" -le 0 ]] && break
[[ -n "${released[$n]:-}" ]] && continue

labels="$(labels_of "$n")"
if has_label "$labels" "$HANDS_OFF_LABEL"; then
log " #$n — skip: $HANDS_OFF_LABEL (needs a human)."
continue
fi
if has_label "$labels" "$HOLD_LABEL"; then
log " #$n — skip: $HOLD_LABEL (held)."
continue
fi

open_blockers="$(
gh api "repos/$REPO/issues/$n/dependencies/blocked_by" \
--jq '[.[] | select(.state=="open") | .number] | join(",")'
Comment on lines +147 to +148

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Paginate blocked-by dependencies before releasing

When a ready candidate has more than 30 blocked_by dependencies, this call only inspects the first page; I checked GitHub's REST docs for this endpoint, which list per_page with a default of 30 plus page pagination parameters. Because the sub-issues calls above use --paginate but this one does not, an open blocker on page 2+ is missed and the driver can apply dev-lead before all blockers are closed.

Useful? React with 👍 / 👎.

)"
if [[ -n "$open_blockers" ]]; then
log " #$n — blocked by open: [$open_blockers]."
continue
fi

if [[ "$DRY_RUN" = "true" ]]; then
log " #$n — READY (dry-run, not labeling)."
else
gh issue edit "$n" --repo "$REPO" --add-label "$DEV_LEAD_LABEL" >/dev/null
log " #$n — RELEASED: applied '$DEV_LEAD_LABEL'."
fi
slots=$((slots - 1))
released_now=$((released_now + 1))
done

log "Released this run: $released_now."
Loading
Loading