Repository navigation
feat(initiative): dependency-aware driver to deliver epics agentically #507
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
71d1cc3
527a592
8d54d93
4d969f9
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| 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' }} | ||
|
|
||
| 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 | ||
| 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. |
| 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}" | ||
|
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 | ||
|
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 | ||
|
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
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
When a ready candidate has more than 30 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." | ||
Uh oh!
There was an error while loading. Please reload this page.