@plainconceptsplatform/workflows 1.3.1 → 1.5.0

package/loops/workflows/authorize-bot-work.yml

@@ -1,105 +1,105 @@
-# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/authorize-bot-work.yml. Update with `workflows update --force`; consumer edits may be overwritten.
-# Human adds implement/refine/direct/feature label → validates permission → bot adds bot-working
-# This ensures the bot is the actor for all agentic workflows.
-#
-# IMPORTANT: Only triggers for HUMAN actors. When the bot transitions refine→implement,
-# it adds bot-working itself, so authorize-bot-work must not fire again.
-name: "Authorize Bot Work"
-
-run-name: "Authorizing: ${{ github.event.issue.title }} (#${{ github.event.issue.number }})"
-
-on:
-  issues:
-    types: [labeled]
-
-permissions:
-  contents: read
-
-jobs:
-  authorize:
-    # Only trigger for work labels from HUMANS (not bots), and only if another bot run does not
-    # already own the issue.
-    #
-    # `review` is deliberately NOT excluded. It used to be, and that made the label a one-way
-    # door: the classifier refuses to route while `review` is set, so a person adding `refine`
-    # to a parked issue got no run, no comment and no error anywhere. Triage's own
-    # needs-maintainer verdict tells the maintainer to add `refine`, which could not work.
-    #
-    # A person adding a work label IS the human review the label was waiting for, so this
-    # workflow clears it below before handing the issue to the bot. The classifier's own guard
-    # stays as it is: it exists to stop the *bot* re-triggering itself, and by the time
-    # bot-working is added `review` is already gone.
-    if: >
-      (github.event.label.name == 'implement' ||
-       github.event.label.name == 'refine') &&
-      !contains(github.event.issue.labels.*.name, 'bot-working') &&
-      !endsWith(github.actor, '[bot]')
-    runs-on: [agents-aw, "affinity-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}"]
-    timeout-minutes: 5
-    concurrency:
-      group: authorize-${{ github.event.issue.number }}
-      cancel-in-progress: false
-    permissions:
-      contents: read
-      issues: write
-    steps:
-      - name: Check actor permission
-        id: check
-        env:
-          GH_TOKEN: ${{ github.token }}
-          ACTOR: ${{ github.actor }}
-        run: |
-          set -euo pipefail
-          
-          permission=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$ACTOR/permission" \
-            --jq '.permission' 2>/dev/null || echo "none")
-          
-          case "$permission" in
-            admin | maintain | write)
-              echo "authorized=true" >> "$GITHUB_OUTPUT"
-              echo "::notice::$ACTOR has $permission permission - authorized"
-              ;;
-            *)
-              echo "authorized=false" >> "$GITHUB_OUTPUT"
-              echo "::warning::$ACTOR has '$permission' permission - not authorized"
-              ;;
-          esac
-
-      - name: Checkout for App token action
-        if: steps.check.outputs.authorized == 'true'
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-
-      - name: Generate App token
-        if: steps.check.outputs.authorized == 'true'
-        id: app-token
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
-        with:
-          app-id: ${{ secrets.BOT_APP_ID }}
-          private-key: ${{ secrets.BOT_PRIVATE_KEY }}
-
-      - name: Bot takes the issue over
-        if: steps.check.outputs.authorized == 'true'
-        env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          ISSUE_NUMBER: ${{ github.event.issue.number }}
-          LABEL: ${{ github.event.label.name }}
-        run: |
-          set -euo pipefail
-
-          # Clear review FIRST. A person adding a work label is the human review the label was
-          # waiting for, and the classifier refuses to route an issue that still carries it, so
-          # removing it here is what makes the hand-off work at all. It also has to happen
-          # before bot-working, because that is the event the classifier reads: adding
-          # bot-working first would raise an event whose payload still shows review.
-          # --remove-label on an absent label is a no-op, so this is safe on a fresh issue.
-          # `stalled` goes with it: a person taking the issue on restarts the work, so the
-          # marker the janitor retries on must not survive into the new run.
-          gh issue edit "$ISSUE_NUMBER" --remove-label "review" --remove-label "stalled" 2>/dev/null ||
-            echo "::notice::no review or stalled label to clear on #$ISSUE_NUMBER"
-
-          echo "Adding bot-working label to issue #$ISSUE_NUMBER (triggered by $LABEL)"
-          gh issue edit "$ISSUE_NUMBER" --add-label "bot-working"
-
-          echo "::notice::bot-working label added - bot will now own the $LABEL workflow"
+# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/authorize-bot-work.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+# Human adds implement/refine/direct/feature label → validates permission → bot adds bot-working
+# This ensures the bot is the actor for all agentic workflows.
+#
+# IMPORTANT: Only triggers for HUMAN actors. When the bot transitions refine→implement,
+# it adds bot-working itself, so authorize-bot-work must not fire again.
+name: "Authorize Bot Work"
+
+run-name: "Authorizing: ${{ github.event.issue.title }} (#${{ github.event.issue.number }})"
+
+on:
+  issues:
+    types: [labeled]
+
+permissions:
+  contents: read
+
+jobs:
+  authorize:
+    # Only trigger for work labels from HUMANS (not bots), and only if another bot run does not
+    # already own the issue.
+    #
+    # `review` is deliberately NOT excluded. It used to be, and that made the label a one-way
+    # door: the classifier refuses to route while `review` is set, so a person adding `refine`
+    # to a parked issue got no run, no comment and no error anywhere. Triage's own
+    # needs-maintainer verdict tells the maintainer to add `refine`, which could not work.
+    #
+    # A person adding a work label IS the human review the label was waiting for, so this
+    # workflow clears it below before handing the issue to the bot. The classifier's own guard
+    # stays as it is: it exists to stop the *bot* re-triggering itself, and by the time
+    # bot-working is added `review` is already gone.
+    if: >
+      (github.event.label.name == 'implement' ||
+       github.event.label.name == 'refine') &&
+      !contains(github.event.issue.labels.*.name, 'bot-working') &&
+      !endsWith(github.actor, '[bot]')
+    runs-on: [agents-aw, "affinity-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}"]
+    timeout-minutes: 5
+    concurrency:
+      group: authorize-${{ github.event.issue.number }}
+      cancel-in-progress: false
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Check actor permission
+        id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ACTOR: ${{ github.actor }}
+        run: |
+          set -euo pipefail
+          
+          permission=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$ACTOR/permission" \
+            --jq '.permission' 2>/dev/null || echo "none")
+          
+          case "$permission" in
+            admin | maintain | write)
+              echo "authorized=true" >> "$GITHUB_OUTPUT"
+              echo "::notice::$ACTOR has $permission permission - authorized"
+              ;;
+            *)
+              echo "authorized=false" >> "$GITHUB_OUTPUT"
+              echo "::warning::$ACTOR has '$permission' permission - not authorized"
+              ;;
+          esac
+
+      - name: Checkout for App token action
+        if: steps.check.outputs.authorized == 'true'
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Generate App token
+        if: steps.check.outputs.authorized == 'true'
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_PRIVATE_KEY }}
+
+      - name: Bot takes the issue over
+        if: steps.check.outputs.authorized == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          LABEL: ${{ github.event.label.name }}
+        run: |
+          set -euo pipefail
+
+          # Clear review FIRST. A person adding a work label is the human review the label was
+          # waiting for, and the classifier refuses to route an issue that still carries it, so
+          # removing it here is what makes the hand-off work at all. It also has to happen
+          # before bot-working, because that is the event the classifier reads: adding
+          # bot-working first would raise an event whose payload still shows review.
+          # --remove-label on an absent label is a no-op, so this is safe on a fresh issue.
+          # `stalled` goes with it: a person taking the issue on restarts the work, so the
+          # marker the janitor retries on must not survive into the new run.
+          gh issue edit "$ISSUE_NUMBER" --remove-label "review" --remove-label "stalled" 2>/dev/null ||
+            echo "::notice::no review or stalled label to clear on #$ISSUE_NUMBER"
+
+          echo "Adding bot-working label to issue #$ISSUE_NUMBER (triggered by $LABEL)"
+          gh issue edit "$ISSUE_NUMBER" --add-label "bot-working"
+
+          echo "::notice::bot-working label added - bot will now own the $LABEL workflow"

package/loops/workflows/shared/platform-defaults.md

@@ -1,26 +1,26 @@
----
-# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/shared/platform-defaults.md. Update with `workflows update --force`; consumer edits may be overwritten.
-description: Shared network and safe-output defaults for catalog agent workflows, plus the verification rules every worker that builds or pushes has to follow. The body below is runtime-imported into each worker's prompt ahead of its own steps.
-
-network:
-  allowed:
-    - defaults
-    - forge.plainconcepts.com
-    # opencode fetches its model registry from models.opencode.ai at startup; without
-    # this host on the allowlist the fetch blocks bootstrap and the run stalls after
-    # "init" until the runner kills it. The apex "opencode.ai" is not enough.
-    - models.opencode.ai
-    - node
-    - github
-    - dotnet
-    - fonts
-    - login.microsoftonline.com
-    # centralised AgentMemory (App Service); the MCP shim needs it through the egress proxy
-    - agentmemory-pro-01.azurewebsites.net
-
-safe-outputs:
-  threat-detection: false
----
+---
+# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/shared/platform-defaults.md. Update with `workflows update --force`; consumer edits may be overwritten.
+description: Shared network and safe-output defaults for catalog agent workflows, plus the verification rules every worker that builds or pushes has to follow. The body below is runtime-imported into each worker's prompt ahead of its own steps.
+
+network:
+  allowed:
+    - defaults
+    - forge.plainconcepts.com
+    # opencode fetches its model registry from models.opencode.ai at startup; without
+    # this host on the allowlist the fetch blocks bootstrap and the run stalls after
+    # "init" until the runner kills it. The apex "opencode.ai" is not enough.
+    - models.opencode.ai
+    - node
+    - github
+    - dotnet
+    - fonts
+    - login.microsoftonline.com
+    # centralised AgentMemory (App Service); the MCP shim needs it through the egress proxy
+    - agentmemory-pro-01.azurewebsites.net
+
+safe-outputs:
+  threat-detection: false
+---
 
 ## Verification, for every worker that builds or pushes
 

package/loops/workflows/work-router.yml

@@ -457,13 +457,179 @@ jobs:
           if [ "$existing" -gt 0 ]; then
             echo "has-open-pr=true" >> "$GITHUB_OUTPUT"
             echo "::notice::Issue #$ISSUE_NUMBER already has an open bot PR. Skipping implement to prevent duplicates."
+            exit 0
+          fi
+
+          # A person working on the issue rarely writes a closing keyword: Pliny-Bot #633 said
+          # "Implements #627", and an hour later the bot opened #639 for the same issue. Any open
+          # pull request by a person that names the issue in its title, body or branch holds it.
+          human=$(gh pr list --repo "$REPO" --state open --json number,author,title,body,headRefName \
+            --jq "[.[]
+              | select((.author.login | startswith(\"app/\") or endswith(\"[bot]\")) | not)
+              | select(((.title + \"\n\" + (.body // \"\")) | test(\"#${ISSUE_NUMBER}([^0-9]|$)\"))
+                  or (.headRefName | test(\"(issue|gh)[-_/]?${ISSUE_NUMBER}([^0-9]|$)\"; \"i\")))
+              | .number] | first // empty")
+          if [ -n "$human" ]; then
+            echo "has-open-pr=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::Open PR #$human by a person names #$ISSUE_NUMBER. Skipping implement so the two do not collide."
           else
             echo "has-open-pr=false" >> "$GITHUB_OUTPUT"
           fi
 
+  # A stack child implements on the feature branch its parent issue names. The agent sandbox
+  # cannot resolve that branch itself -- agents have no git credentials and checkout a pinned
+  # default-branch SHA -- so the router reads the marker and resolves the dispatch ref before
+  # the worker starts. Refine stamps `<!-- stack-root-branch: feat/N -->` both on the PARENT
+  # feature issue and on every child body at hand-over, so the child is self-describing for
+  # the implement prompt, which reads only the child's context. The split-parent chain is the
+  # fallback when a child predates the stamp (retries of issues split by an earlier refine).
+  # Missing, empty or garbled markers fail closed: the child takes the flat call-implement
+  # path and lands on the default branch, exactly what a repo without stacks does today.
+  # The in-flight check exists because a dispatched agent-implement run is invisible to
+  # check-implement-pr's older-run dupe check: this router run completes as soon as
+  # `gh workflow run` returns (fire-and-forget), while a workflow_call caller stays
+  # in_progress -- and the dispatch run's title "Working (Implement)" and the App-token
+  # label events' actor "app/..." both miss the title conditions that check matches.
+  # head_branch is the discriminator: a dispatched implement's run records the dispatch ref,
+  # feat/N, while a workflow_call run's head_branch is the default branch. Filtering
+  # in_progress/queued agent-implement.lock.yml runs by head_branch therefore isolates stack
+  # implements with zero effect on flat runs.
+  check-stack-branch:
+    needs: [classify, authorize]
+    if: needs.classify.outputs.route == 'implement' && needs.authorize.outputs.trusted == 'true'
+    runs-on: agents-arc
+    timeout-minutes: 3
+    permissions:
+      contents: read
+      issues: write
+      actions: read
+    outputs:
+      is-stack: ${{ steps.stack.outputs.is-stack }}
+      stack-branch: ${{ steps.stack.outputs.stack-branch }}
+      stack-in-flight: ${{ steps.inflight.outputs.stack-in-flight }}
+      stack-blocked: ${{ steps.blocked.outputs.stack-blocked }}
+    steps:
+      - name: Resolve the feature branch from the stack markers
+        id: stack
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          ISSUE_NUMBER: ${{ needs.classify.outputs.issue-number }}
+        run: |
+          set -euo pipefail
+          echo "is-stack=false" >> "$GITHUB_OUTPUT"
+          echo "stack-branch=" >> "$GITHUB_OUTPUT"
+
+          # Read failures degrade to the flat path, never to a failed job: call-implement
+          # names this job in its needs, so a failure here would block a perfectly ordinary
+          # flat implement run. A repo without stack markers must behave exactly as before.
+          body=$(gh issue view "$ISSUE_NUMBER" --repo "$REPO" --json body --jq '.body // ""' 2>/dev/null || echo '')
+          # Marker-first: the child may carry its own resolved marker from an earlier hop.
+          # `|| true` on both pipelines: under `set -o pipefail`, grep's exit 1 on no match
+          # (the common flat case) or head's SIGPIPE on a multi-marker body must not fail
+          # the job -- call-implement needs this job, so a failure here would block flat
+          # implements too.
+          branch=$(printf '%s' "$body" | grep -oE '<!-- stack-root-branch: [^ ]+ -->' | head -1 | sed -E 's/<!-- stack-root-branch: ([^ ]+) -->/\1/' || true)
+
+          if [ -z "$branch" ]; then
+            # No marker on the child: follow the split-parent chain to the feature issue,
+            # where refine stamps the stack root.
+            parent=$(printf '%s' "$body" \
+              | grep -oE '<!-- split-parent: [0-9]+ -->' | head -1 \
+              | grep -oE '[0-9]+' || true)
+            if [ -n "$parent" ]; then
+              parent_body=$(gh issue view "$parent" --repo "$REPO" --json body --jq '.body // ""' 2>/dev/null || echo '')
+              branch=$(printf '%s' "$parent_body" \
+                | grep -oE '<!-- stack-root-branch: [^ ]+ -->' | head -1 \
+                | sed -E 's/<!-- stack-root-branch: ([^ ]+) -->/\1/' || true)
+            fi
+          fi
+
+          # Fail closed on anything unreadable or unsafe: a missing marker, a garbled
+          # split parent, or a marker naming a deleted branch all take the flat path.
+          if ! printf '%s' "$branch" | grep -qE '^[A-Za-z0-9._/-]+$'; then
+            echo "::notice::Issue #$ISSUE_NUMBER carries no readable stack-root-branch marker; taking the flat path."
+            exit 0
+          fi
+          if ! gh api "repos/$REPO/branches/$(printf '%s' "$branch" | sed 's|/|%2F|g')" --jq '.name' >/dev/null 2>&1; then
+            echo "::notice::Stack root branch $branch no longer exists on the remote; taking the flat path."
+            echo "stack-branch=$branch" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "is-stack=true" >> "$GITHUB_OUTPUT"
+          echo "stack-branch=$branch" >> "$GITHUB_OUTPUT"
+
+      # A child whose `Blocked by #N` sibling has not landed is held, not dispatched: dispatched now
+      # it would cut from a feature branch that lacks the sibling's work. Lyceum #112 (units,
+      # blocked by #111, modules) was dispatched alongside #111 and would have built units on a
+      # feat/45 with no modules. The in-flight check below cannot catch that: both routers ran
+      # before either dispatch existed, and serialising runs would still start #112 before #111's
+      # pull request merged. The landing of the blocker releases the child (the stack block in
+      # detect-pr-conflicts). Held, it keeps `implement` and loses `bot-working`, so it reads as
+      # waiting rather than stuck.
+      - name: Hold a child whose blockers have not landed
+        id: blocked
+        if: steps.stack.outputs.is-stack == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          ISSUE_NUMBER: ${{ needs.classify.outputs.issue-number }}
+          STACK_BRANCH: ${{ steps.stack.outputs.stack-branch }}
+        run: |
+          set -euo pipefail
+          echo "stack-blocked=false" >> "$GITHUB_OUTPUT"
+          body=$(gh issue view "$ISSUE_NUMBER" --repo "$REPO" --json body --jq '.body // ""' 2>/dev/null || echo '')
+          waiting=""
+          for b in $(printf '%s' "$body" | grep -oiE 'blocked by #[0-9]+' | grep -oE '[0-9]+' | sort -u || true); do
+            gh issue view "$b" --repo "$REPO" --json state --jq '.state' 2>/dev/null | grep -qix open || continue
+            # Open, but landed if a pull request that closes it has merged into the feature branch:
+            # the release fires on that merge and the gate closes the issue a moment later, or not
+            # at all when it fails. Reading the issue state alone would hold the child again with
+            # no later landing left to release it.
+            landed=$(gh pr list --repo "$REPO" --state merged --base "$STACK_BRANCH" --search "#$b in:body"               --json body --jq "[.[] | select(.body | test(\"(?i)(close[sd]?|fix(e[sd])?|resolve[sd]?) #${b}([^0-9]|$)\"))] | length" 2>/dev/null || echo 0)
+            [ "${landed:-0}" -gt 0 ] && continue
+            waiting="$waiting #$b"
+          done
+          [ -n "$waiting" ] || exit 0
+          echo "::notice::#$ISSUE_NUMBER is blocked by$waiting, not yet landed on $STACK_BRANCH; holding it."
+          echo "stack-blocked=true" >> "$GITHUB_OUTPUT"
+          gh issue edit "$ISSUE_NUMBER" --repo "$REPO" --remove-label bot-working >/dev/null 2>&1 || true
+          marker='<!-- stack-held -->'
+          if ! gh api "repos/$REPO/issues/$ISSUE_NUMBER/comments?per_page=100" --jq '.[].body' 2>/dev/null | grep -qF "$marker"; then
+            {
+              printf '%s\n' "$marker"
+              printf "Held until%s have landed on \`%s\`: this child builds on them. It keeps \`implement\` and is released when they merge.\n" "$waiting" "$STACK_BRANCH"
+            } > /tmp/held.md
+            gh issue comment "$ISSUE_NUMBER" --repo "$REPO" --body-file /tmp/held.md >/dev/null || true
+          fi
+
+      - name: Detect an in-flight implement on the feature branch
+        id: inflight
+        if: steps.stack.outputs.is-stack == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          STACK_BRANCH: ${{ steps.stack.outputs.stack-branch }}
+        run: |
+          set -euo pipefail
+          echo "stack-in-flight=false" >> "$GITHUB_OUTPUT"
+          # Only dispatched stack implements run with head_branch = feat/N; a workflow_call
+          # (flat) implement run's head_branch is the default branch, so this filter never
+          # sees it. This closes the dupe-visibility gap left by fire-and-forget dispatch.
+          for status in in_progress queued; do
+            live=$(gh api "repos/$REPO/actions/workflows/agent-implement.lock.yml/runs?status=$status&per_page=100" \
+              --jq "[.workflow_runs[] | select(.head_branch == \"${STACK_BRANCH}\")] | length" 2>/dev/null || echo 0)
+            if [ "${live:-0}" -gt 0 ]; then
+              echo "::notice::An implement run is already in flight on $STACK_BRANCH; skipping dispatch."
+              echo "stack-in-flight=true" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+          done
+
   call-implement:
-    needs: [classify, authorize, check-implement-pr]
-    if: needs.classify.outputs.route == 'implement' && needs.authorize.outputs.trusted == 'true' && needs.check-implement-pr.outputs.has-open-pr != 'true'
+    needs: [classify, authorize, check-implement-pr, check-stack-branch]
+    if: needs.classify.outputs.route == 'implement' && needs.authorize.outputs.trusted == 'true' && needs.check-implement-pr.outputs.has-open-pr != 'true' && needs.check-stack-branch.outputs.is-stack != 'true'
     uses: ./.github/workflows/agent-implement.lock.yml
     concurrency:
       group: implement-global
@@ -483,6 +649,50 @@ jobs:
       BOT_PRIVATE_KEY: ${{ secrets.BOT_PRIVATE_KEY }}
       AGENTMEMORY_SECRET: ${{ secrets.AGENTMEMORY_SECRET }}
 
+  # Stack children dispatch agent-implement by `gh workflow run --ref feat/N` instead of calling
+  # it: a workflow_call would pin the callee to THIS event's SHA, which for a label event is
+  # the default branch, not the feature branch. Dispatch on the feature ref makes the callee's
+  # GITHUB_SHA the feature tip, so the agent patches exactly the tree its PR will target, and
+  # the compile-time checkout ternary keys off `workflow_dispatch` to checkout github.ref_name.
+  # The dispatch itself carries no secrets (gh workflow run cannot forward them); the
+  # dispatched run reads REPO-LEVEL OPENAI_API_KEY / CODEX_API_KEY / COPILOT_GITHUB_TOKEN, the
+  # stack-activation prerequisite documented alongside the markers. BOT_APP_ID / BOT_PRIVATE_KEY
+  # are already repo-level. dispatch-triage proves the pattern: same app-token mint, same
+  # `actions: write` scope needed for `gh workflow run`.
+  dispatch-implement:
+    needs: [classify, authorize, check-implement-pr, check-stack-branch]
+    if: >
+      needs.classify.outputs.route == 'implement' &&
+      needs.authorize.outputs.trusted == 'true' &&
+      needs.check-implement-pr.outputs.has-open-pr != 'true' &&
+      needs.check-stack-branch.outputs.is-stack == 'true' &&
+      needs.check-stack-branch.outputs.stack-in-flight != 'true' &&
+      needs.check-stack-branch.outputs.stack-blocked != 'true'
+    runs-on: agents-arc
+    timeout-minutes: 5
+    permissions:
+      actions: write
+      contents: read
+    steps:
+      - name: Create bot token
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          client-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_PRIVATE_KEY }}
+      - name: Dispatch stack implement on the feature branch
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          REPO: ${{ github.repository }}
+          STACK_BRANCH: ${{ needs.check-stack-branch.outputs.stack-branch }}
+          ISSUE_NUMBER: ${{ needs.classify.outputs.issue-number }}
+          ATTEMPTS: ${{ needs.classify.outputs.attempts }}
+        run: |
+          set -euo pipefail
+          gh workflow run agent-implement.lock.yml --repo "$REPO" --ref "$STACK_BRANCH" \
+            -f issue-number="$ISSUE_NUMBER" \
+            -f attempts_so_far="$ATTEMPTS"
+
   dispatch-triage:
     needs: [classify, authorize]
     if: needs.classify.outputs.route == 'triage' && needs.authorize.outputs.is_outside_collaborator == 'true'
@@ -973,6 +1183,139 @@ jobs:
               while IFS= read -r pr; do
                 maybe_dispatch "$pr"
               done
+
+            # Stacked delivery: the merged pull request merged into a feature branch, not the
+            # default branch, so this is a child landing. If the feature branch has no open
+            # children left and its root pull request is green, the stack is complete and a
+            # comment on the root pull request tells the human it is ready for the root merge.
+            # Repos without stack markers never reach the interesting part: the event PR's base
+            # was the default branch, so the guard below fails immediately. Fully idempotent:
+            # the completion comment carries its own marker, and a run that finds it already
+            # present exits without writing anything.
+            event_base=$(gh api "repos/$REPO/pulls/$EVENT_PR" --jq '.base.ref // empty' 2>/dev/null || echo '')
+            if [ -n "$event_base" ] && [ "$event_base" != "$DEFAULT_BRANCH" ]; then
+              echo "PR #$EVENT_PR merged into a feature branch; checking the stack."
+              # The implement worker's pull request closes exactly its own child issue, so
+              # the closed issue comes from the linked closing references (the resolved form
+              # GitHub computes whatever keyword the agent wrote), with the body text as
+              # fallback for a PR created before that guarantee.
+              closed_issue=$(gh pr view "$EVENT_PR" --repo "$REPO" --json closingIssuesReferences \
+                --jq '.closingIssuesReferences[0].number // empty' 2>/dev/null || true)
+              [ -n "$closed_issue" ] || closed_issue=$(gh api "repos/$REPO/pulls/$EVENT_PR" --jq '.body // ""' \
+                | grep -oiE '(closes?|fixes?|resolves?) #[0-9]+' | head -1 | grep -oE '[0-9]+' || true)
+              if [ -z "$closed_issue" ]; then
+                echo "PR #$EVENT_PR closes no issue; not a stack child. Nothing to do."
+              else
+                # Refine stamps the split-parent marker on every child body it hands over, so
+                # the child's own body names the feature issue. The reverse sub-issues
+                # listing has no equivalent per-child lookup: the sub-issues API only walks
+                # downward from the parent.
+                parent=$(printf '%s' "$(gh issue view "$closed_issue" --repo "$REPO" --json body --jq '.body // ""' 2>/dev/null || echo '')" \
+                  | grep -oE '<!-- split-parent: [0-9]+ -->' | head -1 | grep -oE '[0-9]+' || true)
+                if [ -z "$parent" ]; then
+                  echo "#$closed_issue is not a stack child issue (no parent found); nothing stack-related to do."
+                else
+                  root_pr=$(printf '%s' "$(gh issue view "$parent" --repo "$REPO" --json body --jq '.body // ""' 2>/dev/null || echo '')" \
+                    | grep -oE '<!-- stack-root-pr: [0-9]+ -->' | head -1 | grep -oE '[0-9]+' || true)
+                  # Case-insensitive on purpose, here and in the child count below: `gh pr view` and
+                  # `gh issue view` read GraphQL and answer OPEN, where the REST API answers open. An
+                  # exact `open` never matched, so no root was ever open and no child was ever counted
+                  # open, and the stack-complete announcement could not fire (Lyceum #44, router run
+                  # 38752856518: "Stack #44 has no open root pull request" with #70 open).
+                  root_open=false
+                  [ -n "$root_pr" ] && root_open=$(gh pr view "$root_pr" --repo "$REPO" --json state --jq '.state' 2>/dev/null | grep -qix open && echo true || echo false)
+                  if [ "$root_open" != true ]; then
+                    echo "Stack #$parent has no open root pull request; nothing to announce."
+                  else
+                    # The same child listing refine uses to hand work out: the sub-issues
+                    # link safe_outputs writes, with the body-marker search as fallback. A
+                    # stack parent always has children, so a listing that finds none means
+                    # the lookups failed, and announcing completion of a stack we cannot
+                    # see would be wrong -- stay silent and let a rerun decide.
+                    children=$(gh api "repos/$REPO/issues/$parent/sub_issues" --jq '.[].number' 2>/dev/null || true)
+                    if [ -z "$children" ]; then
+                      children=$(gh issue list --repo "$REPO" --state open --limit 50 \
+                        --search "\"<!-- split-parent: ${parent} -->\" in:body" --json number --jq '.[].number' || true)
+                    fi
+                    if [ -z "$children" ]; then
+                      echo "Cannot list any child of stack #$parent; leaving completion undetected for a rerun."
+                    else
+                    # Release the children this landing unblocks. check-stack-branch holds a child
+                    # whose `Blocked by #N` sibling is still open, and nothing else re-dispatches it,
+                    # so the landing does: re-adding `implement` with the App token is a bot label
+                    # event, which the router routes straight to implement. The child that just
+                    # landed counts as done even before the gate closes its issue a moment later.
+                    for child in $children; do
+                      [ "$child" = "$closed_issue" ] && continue
+                      meta=$(gh issue view "$child" --repo "$REPO" --json state,labels,body 2>/dev/null || echo '{}')
+                      printf '%s' "$meta" | jq -e '(.state // "" | ascii_downcase) == "open"' >/dev/null || continue
+                      printf '%s' "$meta" | jq -e '[.labels[]?.name] | (index("implement") != null) and (index("bot-working") == null)' >/dev/null || continue
+                      blockers=$(printf '%s' "$meta" | jq -r '.body // ""' | grep -oiE 'blocked by #[0-9]+' | grep -oE '[0-9]+' | sort -u || true)
+                      [ -n "$blockers" ] || continue
+                      waiting=""
+                      for b in $blockers; do
+                        [ "$b" = "$closed_issue" ] && continue
+                        if gh issue view "$b" --repo "$REPO" --json state --jq '.state' 2>/dev/null | grep -qix open; then
+                          waiting="$waiting #$b"
+                        fi
+                      done
+                      if [ -n "$waiting" ]; then
+                        echo "#$child still waits on$waiting."
+                        continue
+                      fi
+                      gh issue edit "$child" --repo "$REPO" --remove-label implement >/dev/null 2>&1 || true
+                      gh issue edit "$child" --repo "$REPO" --add-label implement >/dev/null
+                      echo "Released #$child: everything it was blocked by has landed."
+                    done
+                    open_children=0
+                    for child in $children; do
+                      # Landed, though the gate may not have closed its issue yet.
+                      [ "$child" = "$closed_issue" ] && continue
+                      if gh issue view "$child" --repo "$REPO" --json state --jq '.state' 2>/dev/null | grep -qix open; then
+                        open_children=$((open_children + 1))
+                      fi
+                    done
+                    if [ "$open_children" -gt 0 ]; then
+                      echo "$open_children child issue(s) still open on stack #$parent; the stack continues."
+                    else
+                      # The root pull request must be green and mergeable. Green: a successful
+                      # CI run on its head SHA. Mergeable: the same on-demand computation
+                      # every gate dispatch already relies on; UNKNOWN settles in the
+                      # background, so ask until it does, like mergeable_state() does.
+                      root_state=UNKNOWN
+                      for _ in 1 2 3 4 5 6; do
+                        root_state=$(gh pr view "$root_pr" --repo "$REPO" --json mergeable --jq '.mergeable' 2>/dev/null || echo UNKNOWN)
+                        [ "$root_state" = "UNKNOWN" ] || break
+                        sleep 5
+                      done
+                      root_sha=$(gh api "repos/$REPO/pulls/$root_pr" --jq '.head.sha')
+                      root_ci=$(gh api "repos/$REPO/actions/runs?head_sha=$root_sha&per_page=100" \
+                        --jq '[.workflow_runs[]
+                          | select(.name == env.CI_WORKFLOW_NAME and .status == "completed"
+                                   and .conclusion == "success")]
+                        | sort_by(.created_at) | last // empty')
+                      if [ -z "$root_ci" ] || [ "$root_state" != "MERGEABLE" ]; then
+                        echo "Root PR #$root_pr is not green/mergeable yet; the human will merge when it is."
+                      else
+                        completion_marker='<!-- stack-complete -->'
+                        # The announcement is a pull request comment, and pull request
+                        # comments live at the issue endpoint for the pull request number,
+                        # so the marker is looked for where the comment was posted.
+                        already=$(gh api "repos/$REPO/issues/$root_pr/comments?per_page=100" \
+                          --jq "[.[] | select(.body | contains(\"$completion_marker\"))] | length" 2>/dev/null || echo 0)
+                        if [ "${already:-0}" -gt 0 ]; then
+                          echo "Stack #$parent already has a completion announcement; staying silent."
+                        else
+                          gh pr comment "$root_pr" --repo "$REPO" --body "Stack complete: all children have merged into the feature branch and CI is green. This root pull request is ready for a human to review and merge into $DEFAULT_BRANCH. $completion_marker"
+                          echo "Stack #$parent complete: announced root PR #$root_pr."
+                        fi
+                      fi
+                    fi
+                    fi
+                  fi
+                fi
+              fi
+            fi
           else
             maybe_dispatch "$EVENT_PR"
           fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/workflows",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",