feat(decision-brief): wire the decision-brief stage (Mary → ideas/<slug>/brief.md at Ripe)

.github/workflows/decision-brief-reusable.yml

@@ -0,0 +1,168 @@
+# Reusable Decision Brief — fleet dispatch workflow.
+# Single source of truth for the org: the dispatch logic lives here. Repo-level
+# decision-brief.yml files are thin caller stubs
+# (standards/workflows/decision-brief.yml in this repo until it is promoted to
+# combsmith/.github/standards/workflows/).
+#
+# Two signals from the CALLER repo reach the CENTRAL decision-brief workflow in
+# combsmith/.github-private, which runs Mary (the BMAD Analyst) there with the
+# caller as `target_repo` — the brief PR is opened in the caller:
+#   - `needs-brief` added to an Ideas Discussion  -> one brief for that idea
+#   - the caller's schedule / manual dispatch      -> sweep: one brief per idea
+#     idea-triage ranked "Ripe" in the caller's Idea Promotion Queue that has no
+#     brief yet (capped per sweep)
+#
+# It does NOT draft inline: the vendored BMAD frameworks and the provenance
+# guard live centrally, and claude-code-action aborts on `discussion` event
+# contexts ("Unsupported event type: discussion"). The `needs-brief` label stays
+# the human request; the dispatch is an invisible bridge (same pattern as
+# initiative-planner-reusable.yml / idea-triage-reusable.yml in combsmith/.github).
+#
+# IMPORTANT — the dispatch requires a PAT, not GITHUB_TOKEN:
+#   GitHub does not start new workflow runs from a workflow_dispatch fired with
+#   the default GITHUB_TOKEN (loop prevention). The dispatch MUST use a PAT with
+#   workflow scope (GH_PAT_DON_PETRY, or the legacy GH_PAT_WORKFLOWS).
+#
+# Requires (org secrets): GH_PAT_DON_PETRY (or GH_PAT_WORKFLOWS).
+name: Decision Brief — Fleet Dispatch (Reusable)
+
+on:
+  workflow_call:
+    inputs:
+      central_repo:
+        description: "owner/repo hosting the central decision-brief.yml workflow."
+        required: false
+        default: "combsmith/.github-private"
+        type: string
+      central_ref:
+        # Must match the channel the caller's `uses:` pins (the dev-lead
+        # stub's `agent_ref` convention): `gh workflow run` without --ref runs
+        # the central workflow and its tooling from the DEFAULT branch, which
+        # would defeat the release isolation the channel tag exists for.
+        description: "Ref (channel tag or branch) of central_repo to run the central workflow at. Keep it equal to the channel this reusable is pinned at."
+        required: false
+        default: "decision-brief/v1-stable"
+        type: string
+      discussion:
+        description: "Ideas Discussion number to brief (manual dispatch from the caller). Empty on label/schedule events."
+        required: false
+        default: ""
+        type: string
+      label:
+        description: "Discussion label that requests a brief."
+        required: false
+        default: "needs-brief"
+        type: string
+      max_briefs:
+        description: "Sweep cap: how many Ripe ideas one sweep may dispatch briefs for."
+        required: false
+        default: "3"
+        type: string
+    secrets:
+      GH_PAT_DON_PETRY:
+        description: "Canonical org PAT — preferred over GH_PAT_WORKFLOWS when present"
+        required: false
+      GH_PAT_WORKFLOWS:
+        description: "Classic PAT with repo + workflow scope used to dispatch the central decision-brief (GITHUB_TOKEN cannot start a workflow_dispatch run)."
+        required: false
+
+permissions: {}  # no default permissions; each job grants only what it needs
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions: {}
+    # Fire on: the configured label added to a Discussion; a schedule or manual
+    # dispatch of the caller (sweep, or a single idea when `discussion` is set).
+    # Any other caller event is ignored.
+    if: >-
+      (github.event_name == 'discussion' && github.event.action == 'labeled' && github.event.label.name == inputs.label) ||
+      github.event_name == 'schedule' ||
+      github.event_name == 'workflow_dispatch'
+    env:
+      GH_TOKEN: ${{ secrets.GH_PAT_DON_PETRY || secrets.GH_PAT_WORKFLOWS }}
+      CENTRAL_REPO: ${{ inputs.central_repo }}
+      CENTRAL_REF: ${{ inputs.central_ref }}
+      TARGET_REPO: ${{ github.repository }}
+    steps:
+      - name: Guard — PAT present, ref well-formed
+        run: |
+          if [ -z "${GH_TOKEN}" ]; then
+            echo "::error::GH_PAT_DON_PETRY (or legacy GH_PAT_WORKFLOWS) is required — a workflow_dispatch fired with GITHUB_TOKEN will not start a run."
+            exit 1
+          fi
+          if ! [[ "${CENTRAL_REF}" =~ ^[A-Za-z0-9][A-Za-z0-9._/-]*$ ]]; then
+            echo "::error::central_ref must be a branch or tag name, got: '${CENTRAL_REF}'"
+            exit 1
+          fi
+
+      - name: Guard — trusted actor
+        id: trust
+        # Only admin/write collaborators may spend brief budget by labelling a
+        # Discussion. The discussion `labeled` payload carries no
+        # author_association, so query the collaborator permission API.
+        # Schedule and manual dispatch are trusted by construction.
+        env:
+          REPO: ${{ github.repository }}
+          ACTOR: ${{ github.event.sender.login || github.actor }}
+          EVENT: ${{ github.event_name }}
+        run: |
+          if [ "$EVENT" != "discussion" ]; then
+            echo "trusted=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          # A failed lookup is an API error, not an untrusted actor: fail the
+          # bridge loudly so the requested brief is visibly retriable instead of
+          # silently stranded behind an already-applied label.
+          if ! PERM=$(gh api "repos/${REPO}/collaborators/${ACTOR}/permission" --jq '.permission'); then
+            echo "::error::could not read @${ACTOR}'s permission on ${REPO} — not dispatching; re-apply the label or dispatch by hand once the API recovers"
+            exit 1
+          fi
+          case "$PERM" in
+            admin|maintain|write)
+              echo "Actor @${ACTOR} has permission ${PERM} — trusted."
+              echo "trusted=true" >> "$GITHUB_OUTPUT"
+              ;;
+            *)
+              echo "::warning::Actor @${ACTOR} has permission ${PERM} — not trusted; not dispatching the brief."
+              echo "trusted=false" >> "$GITHUB_OUTPUT"
+              ;;
+          esac
+
+      - name: Dispatch central decision-brief for this repo
+        if: steps.trust.outputs.trusted == 'true'
+        env:
+          EVENT: ${{ github.event_name }}
+          # The label event carries the Discussion number; a manual dispatch may
+          # pass one through `discussion`; a schedule never has one (sweep).
+          DISCUSSION_NUMBER: ${{ github.event.discussion.number || inputs.discussion }}
+          MAX_BRIEFS: ${{ inputs.max_briefs }}
+        run: |
+          if [ -n "${DISCUSSION_NUMBER}" ]; then
+            # Validate the discussion number before it reaches the gh command line.
+            if ! [[ "${DISCUSSION_NUMBER}" =~ ^[1-9][0-9]*$ ]]; then
+              echo "::error::discussion number must be a positive integer, got: '${DISCUSSION_NUMBER}'"
+              exit 1
+            fi
+            echo "${EVENT} on ${TARGET_REPO} discussion #${DISCUSSION_NUMBER} → dispatching central decision-brief in ${CENTRAL_REPO}@${CENTRAL_REF}."
+            gh workflow run decision-brief.yml \
+              --repo "${CENTRAL_REPO}" --ref "${CENTRAL_REF}" \
+              -f discussion="${DISCUSSION_NUMBER}" \
+              -f target_repo="${TARGET_REPO}" \
+              -f dry_run=false
+            echo "Dispatched decision-brief.yml (discussion=${DISCUSSION_NUMBER}, target_repo=${TARGET_REPO}, dry_run=false)."
+          else
+            echo "${EVENT} on ${TARGET_REPO} → dispatching central decision-brief SWEEP (Ripe ideas without a brief) in ${CENTRAL_REPO}@${CENTRAL_REF}."
+            if ! [[ "${MAX_BRIEFS}" =~ ^[0-9]+$ ]]; then
+              echo "::error::max_briefs must be an integer, got: '${MAX_BRIEFS}'"
+              exit 1
+            fi
+            gh workflow run decision-brief.yml \
+              --repo "${CENTRAL_REPO}" --ref "${CENTRAL_REF}" \
+              -f from_queue=true \
+              -f max_briefs="${MAX_BRIEFS}" \
+              -f target_repo="${TARGET_REPO}" \
+              -f dry_run=false
+            echo "Dispatched decision-brief.yml (from_queue=true, max_briefs=${MAX_BRIEFS}, target_repo=${TARGET_REPO}, dry_run=false)."
+          fi