@plainconceptsplatform/workflows 1.3.0 → 1.4.0

package/loops/workflows/agent-refine.md

@@ -53,6 +53,7 @@ env:
   SPLIT_PARENT_PREFIX: "<!-- split-parent: "
   SPLIT_THRESHOLD: "8"
   MAX_SPLIT_CHILDREN: "6"
+  MIN_CHILD_POINTS: "3"
   INCOMPLETE_COMMENT: "Automated refinement ended without an outcome. The refine label remains for a retry."
   SAFE_OUTPUT_COMMENT_PREFIX: "Refinement update"
   ISSUE_CONTEXT_PATH: /tmp/gh-aw/agent/issue-context.json
@@ -396,6 +397,7 @@ jobs:
           update-issues: 'true'
           create-issues: 'true'
           fallback-issue-number: ${{ inputs.issue-number }}
+          parent-issue: ${{ needs.validate_output.outputs.outcome == 'split' && inputs.issue-number || '' }}
       - name: Apply complete refinement labels
         if: needs.validate_output.outputs.outcome == 'complete'
         uses: ./.github/actions/add-issue-labels
@@ -434,6 +436,83 @@ jobs:
             ${{ env.REFINE_LABEL }}
             ${{ env.WORKING_LABEL }}
             ${{ env.REVIEW_LABEL }}
+      # The stack root pull request. Every output in this worker is staged and applied by this
+      # job, and gh-aw's handler opens nothing while the run is staged: a per-output
+      # `staged: false` on create-pull-request compiles into the handler config and is ignored
+      # there (Lyceum #45, run 38740216266: "Pull request creation preview written to step
+      # summary"). So the root is opened here, from the agent's own create_pull_request request,
+      # once the validator has called the run a split. Refine writes no code, so the root carries
+      # none: an empty commit on the default branch's tip, created through the API, which is what
+      # gh-aw's allow-empty would have pushed. Idempotent: an open root on the feature branch is
+      # reused and an existing branch is not recreated, so a retry stamps the same root.
+      - name: Open the stack root pull request
+        id: root
+        if: needs.validate_output.outputs.outcome == 'split'
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          REPO: ${{ github.repository }}
+          ISSUE: ${{ inputs.issue-number }}
+          AGENT_OUTPUT: agent-artifact/agent_output.json
+        run: |
+          set -euo pipefail
+          branch="feat/${ISSUE}"
+          item=$(jq -c '[.items[] | select(.type == "create_pull_request")][0] // {}' "$AGENT_OUTPUT")
+          title=$(printf '%s' "$item" | jq -r '.title // empty')
+          body=$(printf '%s' "$item" | jq -r '.body // empty')
+          if [ -z "$title" ]; then
+            title=$(gh issue view "$ISSUE" --repo "$REPO" --json title --jq '.title')
+          fi
+          case "$title" in "[bot] "*) ;; *) title="[bot] ${title}" ;; esac
+          # The root's merge is what ends the feature, so it must close the feature issue.
+          if ! printf '%s' "$body" | grep -qiE "(fixes|closes|resolves) #${ISSUE}([^0-9]|$)"; then
+            body=$(printf '%s\n\nFixes #%s' "$body" "$ISSUE")
+          fi
+
+          existing=$(gh pr list --repo "$REPO" --state open --head "$branch" --json number --jq '.[0].number // empty')
+          if [ -n "$existing" ]; then
+            echo "Reusing open root #${existing} on ${branch}"
+            echo "pr_number=${existing}" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          default=$(gh api "repos/${REPO}" --jq '.default_branch')
+          if ! gh api "repos/${REPO}/git/ref/heads/${branch}" >/dev/null 2>&1; then
+            base_sha=$(gh api "repos/${REPO}/git/ref/heads/${default}" --jq '.object.sha')
+            tree=$(gh api "repos/${REPO}/git/commits/${base_sha}" --jq '.tree.sha')
+            commit=$(gh api "repos/${REPO}/git/commits" -f message="chore: open the stack root for #${ISSUE}" \
+              -f tree="$tree" -f "parents[]=${base_sha}" --jq '.sha')
+            gh api "repos/${REPO}/git/refs" -f ref="refs/heads/${branch}" -f sha="$commit" >/dev/null
+          fi
+          printf '%s' "$body" > /tmp/root-body.md
+          url=$(gh pr create --repo "$REPO" --base "$default" --head "$branch" --title "$title" --body-file /tmp/root-body.md)
+          echo "Opened root ${url} on ${branch}"
+          echo "pr_number=${url##*/}" >> "$GITHUB_OUTPUT"
+      # The stack markers. The feature branch and its root pull request are what every child
+      # builds on and what completion is counted against, so they are recorded on the feature
+      # issue itself, where the child implement runs and the router read them back with no new
+      # service: `<!-- stack-root-branch: ... -->` resolves each child's dispatch ref, and
+      # `<!-- stack-root-pr: ... -->` names the held root. The branch comes from the pull
+      # request itself, never from the name the agent chose, because what reached the remote
+      # is the only truth. Idempotent: old markers are replaced, so a re-split after a
+      # discarded first attempt re-stamps cleanly. Missing markers fail closed -- a child
+      # without them takes the flat path, never a silent feature-branch dispatch.
+      - name: Record the stack root on the issue
+        if: needs.validate_output.outputs.outcome == 'split' && (steps.root.outputs.pr_number != '' || needs.safe_outputs.outputs.created_pr_number != '')
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          REPO: ${{ github.repository }}
+          ISSUE: ${{ inputs.issue-number }}
+          PR_NUMBER: ${{ steps.root.outputs.pr_number || needs.safe_outputs.outputs.created_pr_number }}
+        run: |
+          set -euo pipefail
+          branch=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json headRefName --jq '.headRefName')
+          body=$(gh issue view "$ISSUE" --repo "$REPO" --json body --jq '.body // ""')
+          cleaned=$(printf '%s' "$body" | sed -E 's/<!-- stack-root-(branch|pr): [^ ]+ -->//g' | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}')
+          printf '%s\n\n<!-- stack-root-branch: %s -->\n<!-- stack-root-pr: %s -->' "$cleaned" "$branch" "$PR_NUMBER" > /tmp/issue-body.md
+          gh issue edit "$ISSUE" --repo "$REPO" --body-file /tmp/issue-body.md
+          echo "Stamped stack root branch $branch and PR #$PR_NUMBER on issue #$ISSUE"
       # Estimates become labels here rather than in the agent, because labels are workflow-owned
       # state. Children were created moments ago by the same run, so they are labelled together
       # with the parent: each body carries its own marker.
@@ -507,6 +586,7 @@ jobs:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
           REPO: ${{ github.repository }}
           PARENT: ${{ inputs.issue-number }}
+          ROOT_PR: ${{ steps.root.outputs.pr_number || needs.safe_outputs.outputs.created_pr_number }}
           REFINE_LABEL: ${{ env.REFINE_LABEL }}
           REFINED_LABEL: ${{ env.REFINED_LABEL }}
           IMPLEMENT_LABEL: ${{ env.IMPLEMENT_LABEL }}
@@ -518,6 +598,21 @@ jobs:
             children=$(gh issue list --repo "$REPO" --state open --limit 50 \
               --search "\"<!-- split-parent: ${PARENT} -->\" in:body" --json number --jq '.[].number' || true)
           fi
+
+          # Each child body also carries the resolved feature branch. The implement agent sees
+          # only the child issue's body in its context, never the parent's, so a marker that
+          # lives on the parent alone is invisible to the very prompt that must act on it.
+          # Stamping the branch the root pull request really runs on (headRefName, the same
+          # source of truth the parent marker uses) makes the child self-describing end to
+          # end: the router reads it to resolve the dispatch ref and the agent reads it to set
+          # its pull request base. Idempotent, and skipped entirely when the root pull request
+          # was not created -- without a feature branch there is no stack to describe, and the
+          # child simply takes the flat path.
+          STACK_BRANCH=''
+          if [ -n "$ROOT_PR" ]; then
+            STACK_BRANCH=$(gh pr view "$ROOT_PR" --repo "$REPO" --json headRefName --jq '.headRefName' 2>/dev/null || true)
+          fi
+
           for child in $children; do
             [ "$child" = "$PARENT" ] && continue
             # A child handed over earlier carries the refined label. Handing it again would start
@@ -527,6 +622,12 @@ jobs:
               echo "#$child was already handed over; leaving it alone"
               continue
             fi
+            if [ -n "$STACK_BRANCH" ]; then
+              child_body=$(gh issue view "$child" --repo "$REPO" --json body --jq '.body // ""')
+              cleaned=$(printf '%s' "$child_body" | sed -E 's/<!-- stack-root-branch: [^ ]+ -->//g' | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}')
+              printf '%s\n\n<!-- stack-root-branch: %s -->' "$cleaned" "$STACK_BRANCH" > /tmp/child-body.md
+              gh issue edit "$child" --repo "$REPO" --body-file /tmp/child-body.md >/dev/null
+            fi
             gh issue edit "$child" --repo "$REPO" \
               --remove-label "$REFINE_LABEL" --remove-label "$IMPLEMENT_LABEL" >/dev/null 2>&1 || true
             gh issue edit "$child" --repo "$REPO" --add-label "$REFINED_LABEL" >/dev/null
@@ -744,6 +845,23 @@ safe-outputs:
   # one issue nobody can land; the cap stops a runaway decomposition.
   create-issue:
     max: 6
+  # The stack root. A split story integrates on a feature branch instead of the default
+  # branch: the children land there one by one and the root pull request carries the whole
+  # feature to the default branch once they are done, which is also the human validation
+  # point before main. The branch name is preserved rather than salted because it is a
+  # long-lived integration line that children, markers and prompts all address by name;
+  # a collision with an existing branch fails the push loudly, which is the correct
+  # outcome for a durable ref. The allowed-branches glob must stay in sync with the name
+  # the prompt tells the agent to choose (feat/ plus the parent issue number). Only the
+  # root targets the default branch, so allowed-base-branches admits nothing else.
+  create-pull-request:
+    # Staged like everything else, and opened by the `Open the stack root pull request` step:
+    # gh-aw ignores a per-output `staged: false` while the worker is staged.
+    allowed-branches: ["feat/*"]
+    allowed-base-branches: ["main"]
+    preserve-branch-name: true
+    title-prefix: "[bot] "
+    allow-empty: true
 
 
 # The fleet is two machines, so this clock is also how long a stuck run can hold half of it.
@@ -820,11 +938,24 @@ timeout-minutes: 90
    **If it splits:** write between two and ${{ env.MAX_SPLIT_CHILDREN }} children. Each child is
    a complete refined story wrapped in the same issue form, with its own
    acceptance criteria, its own tests section, and its own estimate of 5 or less. Never write a
-   child estimated at 1: that is a fragment, so fold it into a sibling. Call `create_issue` once
+   child estimated below ${{ env.MIN_CHILD_POINTS }}: that is a fragment, not a story -- the whole
+   stack exists to carry real slices, so fold anything smaller into a sibling and give the
+   sibling the honest combined estimate. Call `create_issue` once
    per child, and in each child body include:
 
    - the line `${{ env.SPLIT_PARENT_PREFIX }}N -->` naming the parent issue number
-   - a `Blocked by #M` line naming any sibling that must land first, when order genuinely matters
+   - a `Blocked by #aw_<id>` line for each sibling that must land first, when order genuinely
+     matters, one line per sibling. Siblings have no numbers yet, so give every child a
+     `temporary_id` of `aw_` plus 3 to 12 letters, digits or underscores (`aw_modules`, not
+     `aw_module_backend`, which gh-aw rejects as too long) and name siblings by it; the workflow rewrites each
+     `#aw_<id>` to the real issue number once the children exist. Write dependencies only as these
+     lines and never set the `blocked_by` field: it takes one reference, and a value naming two
+     rejected the item and discarded the whole refinement (Lyceum #45).
+   - a `Parent feature branch: feat/<parent issue number>` line (for parent #123,
+     `Parent feature branch: feat/123`) naming the branch the whole split integrates on:
+     each child's pull request targets that branch, never the default branch, the children
+     land there one at a time, and only the root pull request carries the finished feature
+     to the default branch
 
    Then call `update_issue` on the parent, replacing its body with a short summary of the whole
    piece of work, the reason it was split, and a checklist linking every child. The parent keeps
@@ -914,7 +1045,23 @@ timeout-minutes: 90
 
     **The story was split.** You estimated ${{ env.SPLIT_THRESHOLD }} or more and found real
     seams. Call `create_issue` once per child, then `update_issue` on the parent with the
-    summary and the checklist, then `add_comment` with `${{ env.REFINE_MARKER }}`, then
+    summary and the checklist. Then open the stack's root pull request, in this order:
+
+    First write the feature's journey as one failing end-to-end test, following the
+    repository's own end-to-end test conventions. That failing test is the specification, not
+    the implementation: write test code only, never the production code that would make it
+    pass. When the repository has no end-to-end test conventions at all, skip the test rather
+    than inventing one -- the root pull request may be proposal-only.
+
+    Then call `create_pull_request` once, with the branch named `feat/` plus the parent issue
+    number -- exactly the name you wrote into every child's `Parent feature branch:` line --
+    a one-line title for the whole feature, and a body carrying that same summary and child
+    checklist plus the closing line `Fixes #${{ inputs.issue-number }}`. Do not pass `base`:
+    the root pull request targets the default branch, and its closing line fires only when it
+    eventually merges there, after every child has landed on the feature branch.
+
+    Finally, call `add_comment` with `${{ env.REFINE_MARKER }}`, then
     `${{ env.SAFE_OUTPUT_COMMENT_PREFIX }}`, then one sentence naming the estimate you gave the
-   whole and how many children you wrote. The children carry the work forward; the parent stays
-   open as their tracker and is never implemented directly.
+    whole, how many children you wrote, and the feature branch they integrate on. The children
+    carry the work forward; the parent stays open as their tracker and is never implemented
+    directly.

package/loops/workflows/work-router.yml

@@ -461,9 +461,160 @@ jobs:
             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 +634,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 +1168,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.0",
+  "version": "1.4.0",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",