@plainconceptsplatform/workflows 1.3.1 → 1.4.0

package/loops/templates/issues/feature_request.yml

@@ -1,75 +1,75 @@
-name: Feature request
-description: Propose a small improvement or new capability
-labels: ["enhancement"]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        This template is for small, well-scoped improvements a focused
-        enhancement, a missing convenience, a quality-of-life fix.
-
-        For large features, architecture changes, or cross-cutting work,
-        open a planning issue or an ADR instead.
-
-        Do **not** include real secrets or production data use placeholders.
-  - type: dropdown
-    id: scope
-    attributes:
-      label: Scope
-      description: How big is this change? If it doesn't fit Small or Medium, use a planning issue instead.
-      options:
-        - Small a single file or component, no refactoring
-        - Medium touches a few files or a feature area, may need minor refactoring
-    validations:
-      required: true
-  - type: textarea
-    id: current-behavior
-    attributes:
-      label: Current behavior
-      description: How does it work today? Describe the existing behavior or limitation.
-    validations:
-      required: true
-  - type: textarea
-    id: problem
-    attributes:
-      label: Problem / motivation
-      description: What user or business need does this address? Why is the current behavior a problem?
-    validations:
-      required: true
-  - type: textarea
-    id: proposal
-    attributes:
-      label: Proposed solution
-      description: What would you like to happen?
-    validations:
-      required: true
-  - type: textarea
-    id: alternatives
-    attributes:
-      label: Alternatives considered
-    validations:
-      required: false
-  - type: textarea
-    id: acceptance
-    attributes:
-      label: Acceptance criteria
-      description: A checklist a reviewer can verify when this is done (include the tests).
-      placeholder: |
-        - [ ] ...
-        - [ ] Tests
-    validations:
-      required: false
-  - type: textarea
-    id: open-questions
-    attributes:
-      label: Open questions
-      description: Decisions a maintainer must make before this can be planned. Leave blank if none.
-    validations:
-      required: false
-  - type: textarea
-    id: related
-    attributes:
-      label: Related links
-      description: Links to related issues, PRs, discussions, or docs. Leave blank if none.
-    validations:
-      required: false
+name: Feature request
+description: Propose a small improvement or new capability
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This template is for small, well-scoped improvements a focused
+        enhancement, a missing convenience, a quality-of-life fix.
+
+        For large features, architecture changes, or cross-cutting work,
+        open a planning issue or an ADR instead.
+
+        Do **not** include real secrets or production data use placeholders.
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      description: How big is this change? If it doesn't fit Small or Medium, use a planning issue instead.
+      options:
+        - Small a single file or component, no refactoring
+        - Medium touches a few files or a feature area, may need minor refactoring
+    validations:
+      required: true
+  - type: textarea
+    id: current-behavior
+    attributes:
+      label: Current behavior
+      description: How does it work today? Describe the existing behavior or limitation.
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What user or business need does this address? Why is the current behavior a problem?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: A checklist a reviewer can verify when this is done (include the tests).
+      placeholder: |
+        - [ ] ...
+        - [ ] Tests
+    validations:
+      required: false
+  - type: textarea
+    id: open-questions
+    attributes:
+      label: Open questions
+      description: Decisions a maintainer must make before this can be planned. Leave blank if none.
+    validations:
+      required: false
+  - type: textarea
+    id: related
+    attributes:
+      label: Related links
+      description: Links to related issues, PRs, discussions, or docs. Leave blank if none.
+    validations:
+      required: false

package/loops/templates/release/github-release.yml

@@ -1,30 +1,30 @@
-# Managed by @plainconceptsplatform/workflows. Source: loops/templates/release/github-release.yml. Update with `workflows update --force`; consumer edits may be overwritten.
-name: Publish GitHub release
-
-on:
-  push:
-    tags:
-      - "v*"
-
-permissions:
-  contents: write
-
-jobs:
-  publish:
-    name: Publish release
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - name: Create or update GitHub release
-        env:
-          GH_TOKEN: ${{ github.token }}
-          TAG: ${{ github.ref_name }}
-        shell: bash
-        run: |
-          set -euo pipefail
-
-          if gh release view "$TAG" >/dev/null 2>&1; then
-            gh release edit "$TAG" --title "$TAG" --generate-notes
-          else
-            gh release create "$TAG" --title "$TAG" --generate-notes
-          fi
+# Managed by @plainconceptsplatform/workflows. Source: loops/templates/release/github-release.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+name: Publish GitHub release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    name: Publish release
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Create or update GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            gh release edit "$TAG" --title "$TAG" --generate-notes
+          else
+            gh release create "$TAG" --title "$TAG" --generate-notes
+          fi

package/loops/workflows/agent-implement.md

@@ -77,8 +77,8 @@ description: |
   Waiting on CI inside this run would hold a runner doing nothing, which is why the gate is
   a separate workflow rather than a later step.
 
-  Router-only worker: triggered exclusively via workflow_call from work-router.yml.
-  Contract input: issue-number.
+  Router-first worker: triggered via workflow_call from work-router.yml, or via workflow_dispatch
+  from the router's stack path (`--ref` = the feature branch). Contract input: issue-number.
 
 name: "Agent: Implement Issue"
 
@@ -101,6 +101,23 @@ on:
         required: false
         type: string
         default: '0'
+  # Stack dispatch (work-router.yml reads `<!-- stack-root-branch: feat/N -->` on the issue and
+  # runs `gh workflow run agent-implement.lock.yml --ref feat/N`). Under workflow_call
+  # GITHUB_SHA is the router event's SHA -- global default-branch state, not the feature
+  # branch -- which widens the patch window; dispatch pins the SHA to the feature tip and makes
+  # the generator produce exactly-the-child's-commits patches. Workflow-level inputs resolve
+  # identically from both triggers, so every job below reads inputs.issue-number unchanged.
+  workflow_dispatch:
+    inputs:
+      issue-number:
+        description: Issue number to implement.
+        required: true
+        type: string
+      attempts_so_far:
+        description: Failed implement runs already made for this issue. Parked when it reaches the cap.
+        required: false
+        type: string
+        default: '0'
   # The gate job that the top-level `if:` reads. gh-aw folds that `if:` into the generated
   # activation job but gives activation no dependency on the job, so the reference resolves
   # to '' and the clause is false -- the agent would never run. The package's own validator
@@ -619,6 +636,17 @@ safe-outputs:
     protected-files: allowed
     allowed-files:
       - "**"
+    # The pull request targets the branch this run was started on, which is the branch the work
+    # was cut from: `main` when the router calls this worker, `feat/N` when it dispatches a stack
+    # child with `--ref feat/N`. Taken from the run rather than asked of the agent, because the
+    # agent was asked and did not: on Lyceum #72 it emitted branch and title with no base, the
+    # handler fell back to the default branch, and a bundle built on feat/44 could not be replayed
+    # onto main (run 38694942046). A repository with no stack markers is never dispatched, so its
+    # base stays `main` exactly as before.
+    base-branch: ${{ github.ref_name }}
+    allowed-base-branches:
+      - "main"
+      - "feat/*"
 
 # The fleet is two machines, so this clock is also how long a stuck run can hold half of it.
 # 240 went on to every worker at once when the provider was slow, which fixed the deaths and
@@ -728,12 +756,14 @@ timeout-minutes: 180
 
    Choose exactly one:
 
-   - **`safeoutputs/create_pull_request`** , the normal path. Propose a pull request against
-     `main` with the verified changes. Its `body` must close the issue
+   - **`safeoutputs/create_pull_request`** , the normal path. Propose a pull request with the
+     verified changes. Do not pass `base`: the workflow sets it to the branch this run started
+     on, which is the branch you are working from, so a stack child lands on its feature branch
+     without you doing anything. The `body` **must close exactly this issue and nothing else**
      (`Closes #${{ inputs.issue-number }}`) and summarise what changed and why. Its `branch` is
-     the branch you are on, the one named in step 1; do not invent another name. You do not need
-     to check whether a pull request already exists for this issue: the router does that before
-     dispatching you and does not start this workflow when one does.
+     the branch you are on, the one named in step 1; do not invent another name. You do not
+     need to check whether a pull request already exists for this issue: the router does
+     that before dispatching you and does not start this workflow when one does.
    - **`safeoutputs/report_incomplete`** , only when infrastructure or tooling prevents you
      from completing the task, such as a pre-existing build failure you cannot fix. Provide a
      specific `reason`.

package/loops/workflows/agent-merge-gate.md

@@ -89,7 +89,9 @@ description: |
   risk assessment is clean, hand to a human when it is not, fix CI when it failed. Called by
   the Work Router; does not trigger on public events.
 
-  The router supplies the CI conclusion and run ID as facts, so there is no polling and no
+  In a stack, a child pull request (its base is the feature branch) merges into that feature
+  branch and its child issue closes with it; the root pull request is held for a person. The
+  router supplies the CI conclusion and run ID as facts, so there is no polling and no
   timeout branch. The conclusion is read from the inputs instead of filtered at the trigger.
 
 name: "Agent: Merge Gate"
@@ -155,6 +157,8 @@ jobs:
       conclusion: ${{ steps.subject.outputs.conclusion }}
       run-id: ${{ steps.subject.outputs.run-id }}
       review_blocked: ${{ steps.review.outputs.review_blocked }}
+      pr_base: ${{ steps.stack.outputs.pr_base }}
+      stack_root: ${{ steps.stack.outputs.stack_root }}
     steps:
       - name: Checkout workflow actions
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -189,6 +193,37 @@ jobs:
             sleep 5
           done
           echo "review_blocked=$([ "$decision" = 'CHANGES_REQUESTED' ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
+      # A child PR in a stack has its base on the feature branch, not main. The rest of the
+      # gate needs both facts measured here, once: which branch this PR merges into, and
+      # whether this PR is the root of a stack (its linked feature issue carries this PR's
+      # number in the `<!-- stack-root-pr: N -->` marker refine stamped when it created the
+      # root PR). The base is always known; the marker only exists in stack repos, so
+      # repos without stacks see no change at all in either output ('' and 'false').
+      - name: Detect the pull request's base and its role in a stack
+        id: stack
+        # Only for a resolved subject. Without one, PR is empty and `gh pr view ""` falls back to
+        # the checked-out branch and fails, so every gate dispatched for a pull request that is
+        # not a subject -- a held stack root whose CI went green, for one -- ended red (Lyceum
+        # #106, run 38750643587: "no pull requests found for branch main"). Skipped, both outputs
+        # are empty, which everything downstream already reads as "not a root".
+        if: steps.subject.outputs.found == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          PR: ${{ steps.subject.outputs.pr }}
+          ISSUE: ${{ steps.subject.outputs.issue }}
+        run: |
+          set -euo pipefail
+          pr_base=$(gh pr view "$PR" --repo "$REPO" --json baseRefName --jq '.baseRefName // ""')
+          stack_root=false
+          if [ -n "$ISSUE" ]; then
+            body=$(gh issue view "$ISSUE" --repo "$REPO" --json body --jq '.body // ""' 2>/dev/null || echo "")
+            if echo "$body" | grep -q "<!-- stack-root-pr: $PR -->"; then
+              stack_root=true
+            fi
+          fi
+          echo "pr_base=$pr_base" >> "$GITHUB_OUTPUT"
+          echo "stack_root=$stack_root" >> "$GITHUB_OUTPUT"
 
   # Rung 4b. Everything the merge decision needs that a shell can establish, measured once,
   # before any model reads the diff. The job kept its name and its `requires_review` and
@@ -525,7 +560,7 @@ jobs:
             Findings and verification on the linked issue: #${{ needs.subject.outputs.issue }}. [View this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
             ${{ env.EVIDENCE_BEFORE_REVIEW == 'true' && contains(fromJson('["human-review","owner-review"]'), needs.validate_output.outputs.outcome) && 'Screenshots of this head follow in their own comment if it carries a verification plan. Approving the pull request merges it.' || '' }}
       - name: Merge approved pull request
-        if: needs.validate_output.outputs.outcome == 'auto-merge'
+        if: needs.validate_output.outputs.outcome == 'auto-merge' && needs.subject.outputs.stack_root != 'true'
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
           REPO: ${{ github.repository }}
@@ -534,6 +569,20 @@ jobs:
           set -euo pipefail
           head_sha=$(gh pr view "$PR" --repo "$REPO" --json headRefOid --jq '.headRefOid')
           gh pr merge "$PR" --repo "$REPO" --squash --match-head-commit "$head_sha"
+      # The root's own gate run stops here: children may still be landing on the feature
+      # branch, and the merge decision for main belongs to a person. The comment says only
+      # what a reader needs: the gate held the root, children merge into the feature branch,
+      # and a human merges the root when the stack completes.
+      - name: Hold a stack root for a human merge
+        if: needs.validate_output.outputs.outcome == 'auto-merge' && needs.subject.outputs.stack_root == 'true'
+        uses: ./.github/actions/create-issue-comment
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          issue-number: ${{ needs.subject.outputs.issue }}
+          body: |
+            **Stack root held.** This pull request is the root of a stack: its children merge
+            into the feature branch, and it merges into ${{ github.event.repository.default_branch }} only when a person
+            does it, after all children have landed and the feature branch validates.
       - name: Release remediated issue
         if: needs.validate_output.outputs.outcome == 'remediated'
         uses: ./.github/actions/remove-issue-labels
@@ -583,6 +632,22 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
           issue-number: ${{ needs.subject.outputs.issue }}
           labels: ${{ env.WORKING_LABEL }}
+      # GitHub's closing keywords never fire when a PR merges into a branch other than the
+      # default, so a child PR landing on the feature branch leaves its issue open — and
+      # "zero open children" would never be reachable. This step closes the child issue
+      # deterministically, exactly the issue this PR implements, with the App token: the
+      # close raises routed events only for issue lifecycle the router already understands,
+      # and `gh issue close` on an already-closed issue is a harmless no-op, making the
+      # step safe to re-run.
+      - name: Close the child issue when the pull request landed on a feature branch
+        if: needs.validate_output.outputs.outcome == 'auto-merge' && needs.subject.outputs.pr_base != '' && needs.subject.outputs.pr_base != github.event.repository.default_branch
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          REPO: ${{ github.repository }}
+          ISSUE: ${{ needs.subject.outputs.issue }}
+        run: |
+          set -euo pipefail
+          gh issue close "$ISSUE" --repo "$REPO" --reason completed || true
       # A person decides this one, so the screenshots come before the decision, in a router run of
       # their own outside the belt. Never on auto-merge: that dispatch would race the merge.
       - name: Replay the verification plan for the reviewer
@@ -934,8 +999,10 @@ timeout-minutes: 120
 4b. **Merge conflict when CI is green.** If the conclusion is `success` and
     `has_conflicts` is `true` (current value: `${{ needs.reserve.outputs.has_conflicts }}`),
     resolve the conflict before assessing risk. You are already on the PR branch.
-    Merge `origin/${{ github.event.repository.default_branch }}` into it
-    (`git merge origin/${{ github.event.repository.default_branch }}`), resolve every
+    Merge `origin/${{ needs.subject.outputs.pr_base }}` into it
+    (`git merge origin/${{ needs.subject.outputs.pr_base }}`; that is the branch this pull
+    request merges into — the default branch for a flat pull request, the feature branch
+    for a stack child), resolve every
     conflict deliberately, commit the merge, and run the verification commands below. Do not
     use `--ours`, `--theirs`, or a blanket conflict-marker deletion without reviewing the
     intended behavior from both sides, and never rebase: the push is fast-forward only.
@@ -1098,8 +1165,9 @@ timeout-minutes: 120
    must not auto-merge the PR.
 
    **If `has_conflicts` is `true` (current value: `${{ needs.reserve.outputs.has_conflicts }}`):** You are already on the PR branch. Resolve the conflict;
-   it is not a reason to hand the PR to a human. Merge `origin/${{ github.event.repository.default_branch }}`
-   into the current branch, resolve every conflict deliberately, stage the resolutions, and
+   it is not a reason to hand the PR to a human. Merge `origin/${{ needs.subject.outputs.pr_base }}`
+   (the branch this pull request merges into) into the current branch, resolve every conflict
+   deliberately, stage the resolutions, and
    commit the merge. Then run verification and push the resulting branch update. Do not use
    `--ours`, `--theirs`, or a blanket conflict-marker deletion without reviewing the intended
    behavior from both sides.

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.