@plainconceptsplatform/workflows 1.3.1 → 1.5.0

package/loops/actions/verify-route-matrix/verify-route-matrix.sh

@@ -1183,19 +1183,21 @@ if [ -f "$HOUSEKEEPING_YML" ]; then
   #
   # Counted on the close shape, not on the words. A bare `state: 'closed'` is also how you ask
   # the API for closed things, and the gate metrics list closed pull requests to find the merges:
-  # counting the string alone reported that listing as a third close. Both real closes state a
+  # counting the string alone reported that listing as a third close. Every real close states a
   # reason, so that is what is counted, and the assertion below keeps the two from drifting apart
-  # by refusing any close that does not.
+  # by refusing any close that does not. The counted set grew with stacks -- a landing child
+  # whose issue close was lost, and a feature issue whose root merged -- and each is named in
+  # the Stacked features section below, so the list here is four, not the original two.
   closes=$(count -cE "state: 'closed', state_reason:" "$HOUSEKEEPING_YML")
   if grep -nE "issues\.update\(.*state: 'closed'" "$HOUSEKEEPING_YML" | grep -qv "state_reason:"; then
     HK_OK=0
     echo "FAIL: housekeeping closes an issue without a state_reason; the close audit counts on it" >&2
   fi
-  if [ "$closes" -eq 2 ]; then
+  if [ "$closes" -eq 4 ]; then
     PASS=$((PASS + 1))
   else
     HK_OK=0
-    echo "FAIL: housekeeping closes issues in ${closes} place(s); only the split parent and its own digest are allowed" >&2
+    echo "FAIL: housekeeping closes issues in ${closes} place(s); the split parent, the stack child, the stack feature and the digest are the four allowed" >&2
   fi
 
   # A retry is a workflow_dispatch, and GitHub starts no workflow run from an event raised
@@ -1611,6 +1613,13 @@ if [ -f "$GATE_VALIDATOR" ] && worker_installed merge-gate; then
                                                  human-review "$(gate_items "$(gate_comment assessed)")" success low false false ''
   gate_case "remediating check-diff is accepted" remediated   "$(gate_items "$(gate_comment remediated),${gate_push}")" success low false false fail
 
+  # The verdict line is read by its shape. Pliny-Bot #639 wrote the bold around the whole line,
+  # and the repair it pushed was discarded twice.
+  gate_bold_line='{"type":"add_comment","item_number":7,"body":"## Remediation Report\n\n**Verdict: remediated**\n"}'
+  gate_prose='{"type":"add_comment","item_number":7,"body":"The verdict is remediated, see the push."}'
+  gate_case "a verdict line bolded whole is read" remediated  "$(gate_items "${gate_bold_line},${gate_push}")" failure low
+  gate_case "a verdict in prose is not a verdict" invalid     "$(gate_items "${gate_prose},${gate_push}")" failure low
+
   # The agent's report decides the rest. This is the rule the whole redesign rests on: an
   # unverified finding is a warning whatever severity it claims, so a model cannot fail the gate
   # by asserting something it did not demonstrate, and cannot pass it by understating one it did.
@@ -2334,6 +2343,16 @@ if worker_installed refine; then
     echo "FAIL: the refine refusal never releases bot-working; a refused issue stays reserved with no run behind it" >&2
   fi
 
+  # The split floor: a split child carries a whole stack's machinery (issue, feature branch,
+  # PR into the branch), so a 1- or 2-point slice is a fragment and must be folded into a
+  # sibling instead. The floor must be pinned through the env var the prompt interpolates,
+  # so a consumer cannot lower it below 3 without editing the worker.
+  if ! grep -qF 'MIN_CHILD_POINTS: "3"' "$REFINE_WORKER_MD" \
+    || ! grep -qF 'child estimated below ${{ env.MIN_CHILD_POINTS }}' "$REFINE_WORKER_MD"; then
+    SIZE_GATE_OK=0
+    echo "FAIL: refine allows split children below 3 points; the floor must stay interpolated from MIN_CHILD_POINTS" >&2
+  fi
+
   if [ "$SIZE_GATE_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
@@ -2620,8 +2639,10 @@ if [ -f "$APP_ERRORS_MJS" ]; then
   # 3. The field allowlist is what actually holds the line, because a redaction rule filters
   # values and cannot see a field somebody adds next year. Compared as a set, so reordering is
   # fine and an addition is not. run_id is the one that matters: it is unhashed on this
-  # telemetry and joins to a conversation and to a person.
-  expected_fields="exceptionType frames fingerprint firstSeen lastSeen occurrences operationName operations problemId roleName topFrames message category"
+  # telemetry and joins to a conversation and to a person. category, fingerprint, message and
+  # topFrames joined in v0.28.7 to enrich the filed issues (a84928a); they are set-side
+  # fields, never engine telemetry, so the allowlist grows with them.
+  expected_fields="category exceptionType fingerprint firstSeen frames lastSeen message occurrences operationName operations problemId roleName topFrames"
   actual_fields="$(sed -n '/export const FINDING_FIELDS = \[/,/\];/p' "$APP_ERRORS_MJS" |
     grep -oE '"[a-zA-Z]+"' | tr -d '"' | sort | tr '\n' ' ' | sed 's/ $//')"
   if [ "$actual_fields" = "$(echo "$expected_fields" | tr ' ' '\n' | sort | tr '\n' ' ' | sed 's/ $//')" ]; then
@@ -2662,9 +2683,202 @@ if [ -f "$APP_ERRORS_MJS" ]; then
   if [ "$AE_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
+echo "── Stacked features ──────────────────────────────────────────────────────"
+
+# Stacks are delivered by marker, not by label: every flat-mode rule still has to hold on a
+# repository that has never seen a marker. The assertions here are grouped as the two halves
+# of that contract. The first says the stack machinery exists and fails closed: an unreadable
+# or missing marker must route a child down the flat path, never dispatch at a branch nobody
+# resolved. The second says the flat path never learned about stacks: the default-path jobs
+# and prompts carry no stack condition that could fire on an issue without markers.
+STACK_OK=1
+st() {
+  grep -qE "$1" "$2" || { STACK_OK=0; echo "FAIL: stacked features ${3}" >&2; }
+}
+# The router's stack job is a block of a derived file, not a file of its own, so its
+# assertions take the block on stdin: handing a multi-line string to grep as a filename
+# fails with "File name too long" and reads as a wiring failure that is not one.
+st_str() {
+  printf '%s' "$2" | grep -qE "$1" || { STACK_OK=0; echo "FAIL: stacked features ${3}" >&2; }
+}
+
+# 1. The resolver. check-stack-branch reads the child's own marker first, then the
+# split-parent chain; both are `|| true` so a flat body (no match) cannot fail the job --
+# call-implement names this job in its needs, so a hard failure would block flat implements.
+CHECK_STACK_JOB=$(sed -n '/^  check-stack-branch:$/,/^  [a-z0-9_-]*:$/p' "$ROUTER_YML")
+if [ -n "$CHECK_STACK_JOB" ]; then
+  st "stack-root-branch: \[\\^ \]\+" "$ROUTER_YML" 'has no marker regex for the feature branch'
+  st_str 'exit 0' "$CHECK_STACK_JOB" 'resolver hard-fails instead of taking the flat path'
+  st_str 'sed .s\|/\|%2F\|g.' "$CHECK_STACK_JOB" 'does not URL-escape the stack branch before the existence check'
+  st_str 'sed -E .s/<!-- stack-root-branch: \(\[\^ \]\+\) -->/\\1/.' "$CHECK_STACK_JOB" 'does not strip the marker syntax off the branch'
+  # The dupe guard: only dispatched stack implements run with head_branch = feat/N, so a
+  # workflow_call (flat) run whose head_branch is the default branch can never match it.
+  st_str 'head_branch == ..\$\{STACK_BRANCH\}..' "$CHECK_STACK_JOB" 'does not detect an in-flight implement on the feature branch'
+  # Dispatch happens on the resolved ref, never on the event SHA. The `gh workflow run`
+  # lives in dispatch-implement, which check-stack-branch gates: the two jobs verify the
+  # branch exists, then hand off. The run needs a fresh App token -- GITHUB_TOKEN can
+  # start no workflow -- and it reads repo-level secrets because a dispatch cannot forward
+  # workflow-call ones, which is the activation prerequisite ownership.md documents.
+  DISPATCH_JOB=$(sed -n '/^  dispatch-implement:$/,/^  [a-z0-9_-]*:$/p' "$ROUTER_YML")
+  if [ -n "$DISPATCH_JOB" ]; then
+    st_str 'gh workflow run agent-implement\.lock\.yml .* --ref "\$STACK_BRANCH"' "$DISPATCH_JOB" 'does not dispatch the stack implement at all'
+    st_str 'create-github-app-token' "$DISPATCH_JOB" 'dispatches with GITHUB_TOKEN, which can start no run'
+    # A child blocked by an open sibling is held, and the sibling's landing releases it. Without
+    # both halves a dependent child cuts from a feature branch that lacks its dependency (Lyceum
+    # #112, dispatched alongside #111), or is held forever.
+    st_str "stack-blocked != 'true'" "$DISPATCH_JOB" 'dispatches a child whose blockers have not landed'
+    st 'name: Hold a child whose blockers have not landed' "$ROUTER_YML" 'never holds a child behind the siblings it is blocked by'
+    st 'state merged --base "\$STACK_BRANCH"' "$ROUTER_YML" 'holds a child behind a blocker whose pull request already landed, which nothing releases again'
+    st 'Released #\$child: everything it was blocked by has landed' "$ROUTER_YML" 'holds blocked children but never releases them'
+  fi
+  # The child's pull request targets the ref the run was dispatched on, taken from the run.
+  # Asking the agent for it failed in practice (Lyceum #72, run 38694942046): it emitted no
+  # base, the handler fell back to the default branch, and a bundle cut from the feature
+  # branch would not replay there. Both halves are checked, because a prompt that asks again
+  # would invite an explicit base that disagrees with the ref.
+  st 'base-branch: \$\{\{ github\.ref_name \}\}' "$IMPLEMENT_WORKER_MD" 'leaves the pull request base to the agent instead of the dispatched ref'
+  if grep -qE 'base="feat/N"|pass `base: "feat/N"`' "$IMPLEMENT_WORKER_MD"; then
+    STACK_OK=0
+    echo "FAIL: stacked features prompt asks the agent for the base again; the run already sets it" >&2
+  fi
+else
+  # check-stack-branch serves only the implement route, so the CLI drops it from a router
+  # that did not install implement. Nothing to assert then, and the section above must not
+  # claim a pass for a job that is legitimately absent.
+  :
+fi
+
+# 2. Completion. The merge of a child PR into a feature branch (base != default branch) is
+# the only event that can mean "one fewer open child". The router block must be idempotent:
+# the announcement carries <!-- stack-complete --> and a re-run that finds it stays silent.
+st 'stack-complete' "$ROUTER_YML" 'has no idempotent completion marker on the root pull request'
+st 'closingIssuesReferences\[0\]\.number // empty' "$ROUTER_YML" 'does not read the child PR to find the closed issue'
+st 'split-parent: \[0-9\]+' "$ROUTER_YML" 'does not walk from the child to its feature issue'
+st 'stack-root-pr: \[0-9\]+' "$ROUTER_YML" 'does not read the root pull request number off the feature issue'
+# gh pr view and gh issue view answer OPEN, not open. An exact lowercase match on their state
+# never matches, which left every root closed and every child done as far as completion knew.
+# The child whose pull request just landed is done even if the gate has not closed its issue yet.
+st '# Landed, though the gate may not have closed its issue yet' "$ROUTER_YML" 'counts the child that just landed as still open, so the stack never reads complete'
+if grep -nE "(gh pr view|gh issue view)[^|]*--json state[^|]*\| *grep -q?x open" "$ROUTER_YML" >/dev/null; then
+  STACK_OK=0
+  echo "FAIL: stacked features compares a GraphQL state (OPEN) to lowercase open; the root and children never read as open" >&2
+fi
+
+# 3. The gate. A child PR that lands on a feature branch closes exactly its own child issue
+# there (GitHub's closing keywords do not fire off the default branch); the root is held
+# for a person with the App token, so anybody reading the timeline can replace it. The
+# marker test on the issue body is what makes both stack-specific and invisible flat.
+if worker_installed merge-gate; then
+  st 'stack-root-pr: \$PR -->' "$MERGE_GATE_WORKER_MD" 'does not test the feature issue for the root marker'
+  st 'needs\.subject\.outputs\.stack_root == .true.' "$MERGE_GATE_WORKER_MD" 'has no root-hold branch before the merge step'
+  # The stack step reads the subject's PR; with no subject it fails on an empty number.
+  gate_stack_step=$(sed -n '/- name: Detect the pull request.s base and its role in a stack/,/run: |/p' "$MERGE_GATE_WORKER_MD")
+  st_str "if: steps.subject.outputs.found == 'true'" "$gate_stack_step" 'runs the stack step without a subject, so a gate dispatched for a held root fails'
+  st '\*\*Stack root held\.\*\*' "$MERGE_GATE_WORKER_MD" 'posts no human-readable hold explanation on the root'
+  st 'gh issue close "\$ISSUE" --repo "\$REPO" --reason completed \|\| true' "$MERGE_GATE_WORKER_MD" 'does not close the child issue when its PR lands off the default branch'
+  st 'needs\.subject\.outputs\.pr_base != .. \&\& needs\.subject\.outputs\.pr_base != github\.event\.repository\.default_branch' "$MERGE_GATE_WORKER_MD" 'gates the child-issue close on the base not being the default branch'
+fi
+
+# 4. The split. Refine creates the feature branch and the held root PR together with the
+# children, then stamps markers on parent and children before any hand-over: the markers are
+# what the resolver, the gate and the janitor read, so no new label exists to move. The root
+# PR body must close the feature issue -- that is what ends the feature when the human merges.
+if worker_installed refine; then
+  REFINE_WORKER_MD="${WORKFLOWS_DIR}/agent-refine.md"
+  st 'allowed-branches: \["feat/\*"\]' "$REFINE_WORKER_MD" 'does not constrain the feature branch name'
+  st 'allowed-base-branches: \["main"\]' "$REFINE_WORKER_MD" 'lets the root target a branch other than the default'
+  st 'preserve-branch-name: true' "$REFINE_WORKER_MD" 'does not preserve the feature branch name on root PR creation'
+  # Refine stages its outputs and applies them itself, and gh-aw opens no pull request while a
+  # worker is staged, not even one marked `staged: false`. The root has to be opened by the
+  # workflow, and the stamp and the hand-over have to read that number, or every child goes flat.
+  st '^  staged: true$' "$REFINE_WORKER_MD" 'no longer stages the body and children for validation before they are applied'
+  st 'name: Open the stack root pull request' "$REFINE_WORKER_MD" 'never opens the root pull request; the staged handler only previews it'
+  st 'PR_NUMBER: \$\{\{ steps\.root\.outputs\.pr_number' "$REFINE_WORKER_MD" 'stamps the stack markers without the root the workflow opened'
+  st 'ROOT_PR: \$\{\{ steps\.root\.outputs\.pr_number' "$REFINE_WORKER_MD" 'hands the children over without the root the workflow opened'
+  st 'stack-root-branch: %s' "$REFINE_WORKER_MD" 'does not stamp the feature branch on the parent issue'
+  st 'Fixes #\$\{\{ inputs\.issue-number \}\}' "$REFINE_WORKER_MD" 'does not make the root PR close the feature issue'
+  # The hand-over stamp: a child handed to implement carries the feature branch marker, so
+  # the resolver reads it off the child body without chasing the chain first.
+  st 'stack-root-branch: %s' "$REFINE_WORKER_MD" 'does not stamp the feature branch on each child at hand-over'
+  # The children have to be found. gh-aw's sanitizer strips HTML comments from agent_output.json,
+  # so the split-parent marker the agent writes never arrives, and staged, nothing links the
+  # children as sub-issues either (Lyceum #45, run 38747143251: three children, none handed over).
+  # The workflow tells the apply which issue the children belong to, and the apply stamps the
+  # marker and links the sub-issue itself.
+  CREATE_ISSUES_ACTION="${HERE}/../create-agent-issues/action.yml"
+  # Dependencies travel as `Blocked by #aw_<id>` lines the apply resolves, never as the
+  # blocked_by field: a value naming two siblings failed the staged preview and threw away a
+  # finished refinement (Lyceum #45, run 38770811334).
+  st 'never set the .blocked_by. field' "$REFINE_WORKER_MD" 'lets the agent express dependencies through blocked_by, which one bad value turns into a lost run'
+  st 'Blocked by #aw_<id>' "$REFINE_WORKER_MD" 'asks for sibling numbers the agent cannot know yet'
+  st 'parent-issue: \$\{\{ needs\.validate_output\.outputs\.outcome == .split.' "$REFINE_WORKER_MD" 'does not tell the apply which issue the split children belong to'
+  st 'issues/\{issue_number\}/sub_issues' "$CREATE_ISSUES_ACTION" 'does not link split children as sub-issues of their parent'
+  st 'split-parent: \$\{parent\}' "$CREATE_ISSUES_ACTION" 'does not stamp the split-parent marker that the sanitizer strips from the agent'
+  # The guard against re-handing a child already handed over: it carries the refined label,
+  # and handing it again would start a second implement on work in flight.
+  st 'grep -qx "\$REFINED_LABEL"' "${WORKFLOWS_DIR}/agent-refine.md" 'does not skip an already-handed-over child'
+fi
+
+# 5. Housekeeping. The janitor's stack section is the backstop for every event the router can
+# miss, and it ran unattended for months before stacks existed. Three of its guardrails are
+# asserted here the way section 3's are. The marker test fails first on a repository without
+# stacks, so the flat cost is one regex per open issue.
+if [ -f "$HOUSEKEEPING_YML" ]; then
+  st 'stack-root-pr: \(\\d\+\)' "$HOUSEKEEPING_YML" 'does not find the feature issues to sweep'
+  st 'implement-pr: \(\\d\+\)' "$HOUSEKEEPING_YML" 'does not read each child pull request number'
+  st "merged_at" "$HOUSEKEEPING_YML" 'does not test whether the child pull request actually landed'
+  # The orphan close: a child whose named PR merged but whose issue never closed is closed
+  # here. Both its closes state a reason, like every other close in the file.
+  if ! grep -qE "github\.rest\.issues\.update\(\{ \.\.\.context\.repo, issue_number: child\.number, state: 'closed', state_reason: 'completed' \}\)" "$HOUSEKEEPING_YML"; then
+    STACK_OK=0
+    echo "FAIL: housekeeping no longer closes an orphaned child whose pull request landed" >&2
+  fi
+  # The flat guarantees. Section 3 must still refuse to close a stack parent (the root PR
+  # closing the feature issue is what ends it, not the sweep), and section 4 must still not
+  # delete a branch whose pull request is open -- an open root PR protects feat/N. The skip
+  # is asserted on its real shape: the marker test inside the issues.some() predicate.
+  st 'stack-root-branch: \\S\+ -->/\.test\(i\.body' "$HOUSEKEEPING_YML" 'no longer skips stack parents in the split-parent close'
+  st "p\.state === 'open'\)\) continue" "$HOUSEKEEPING_YML" 'can delete a feature branch whose root pull request is still open'
+fi
+
+# 6. The compat guarantee, stated as absence. A repository without markers sees none of
+# this: the default path carries no stack condition that could fire. The implement worker's
+# prompt lines that name the markers are conditional on them being present on the issue.
+if worker_installed implement; then
+  # The instruction naming the marker exists (the marker-gated base instruction), and the
+  # flat instruction ("propose against main") is still in place alongside it.
+  st 'stack-root-branch: feat/N -->' "$IMPLEMENT_WORKER_MD" 'does not tell stack children to base their PR on the feature branch'
+  st 'allowed-base-branches:' "$IMPLEMENT_WORKER_MD" 'does not declare the base-branch allowlist for create-pull-request'
+  # The base allowlist denies everything the marker test did not name. main stays first and
+  # unconditional; the feature pattern is additive, never a replacement.
+  if [ "$(count -c '^    allowed-base-branches:' "$IMPLEMENT_WORKER_MD")" -ne 1 ]; then
+    STACK_OK=0
+    echo "FAIL: agent-implement.md declares allowed-base-branches more than once or not at all" >&2
+  fi
+  if ! sed -n '/allowed-base-branches:/,/^  [a-z]/p' "$IMPLEMENT_WORKER_MD" | grep -q '"main"'; then
+    STACK_OK=0
+    echo "FAIL: agent-implement.md allowed-base-branches dropped the default branch" >&2
+  fi
+  # The dispatch trigger must stay optional and marker-gated: a flat implement is a
+  # workflow_call, never a dispatch, so the checkout ternary keys off workflow_dispatch.
+  st 'workflow_dispatch' "$IMPLEMENT_WORKER_MD" 'no longer accepts workflow_dispatch'
+fi
+
+# 7. No stack label anywhere. Stack semantics live in markers on issues and pull requests;
+# a label would have to be moved by the App token to raise events, and every new label is a
+# new consumer-visible surface. Assert the absence of any stack-named label action.
+if grep -nE "add-label .*$|add-labels$" "$ROUTER_YML" "$MERGE_GATE_WORKER_MD" "${WORKFLOWS_DIR}/agent-refine.md" "$IMPLEMENT_WORKER_MD" 2>/dev/null |
+   grep -qiE 'stack'; then
+  STACK_OK=0
+  echo "FAIL: a workflow adds a stack-named label; stack semantics belong to markers" >&2
+fi
+
+if [ "$STACK_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+
 echo
 if [ "$FAIL" -eq 0 ]; then
-  echo "Route matrix: ${PASS} passed"
+  TcMsg="Route matrix: ${PASS} passed"
+  echo "$TcMsg"
 else
   echo "Route matrix: ${PASS} passed, ${FAIL} FAILED" >&2
 fi

package/loops/docs/diagrams.md

@@ -57,7 +57,7 @@ flowchart TD
     wTriage("agent-triage")
     classify -.->|"cron or dispatch"| plumbing
     plumbing["deterministic jobs<br/>no model runs in any of these"] --> pJobs
-    pJobs("bot-approve · audit-close<br/>cleanup-artifacts · validate<br/>reconcile-bot-pr-runs · detect-pr-conflicts")
+    pJobs("bot-approve · audit-close<br/>cleanup-artifacts · validate<br/>reconcile-bot-pr-runs · detect-pr-conflicts<br/>check-stack-branch · dispatch-implement")
     idle(("Idle<br/>run ends, ~10s, every job skipped"))
 
     classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
@@ -83,7 +83,7 @@ flowchart LR
     triage -.->|block| closed(("Closed"))
     triage -.->|needs-info| author("Author replies") --> triage
     write("Write+ user<br/>self-labels") --> refine
-    refine{"refine<br/>estimate in points"} -->|"5 or less"| implement
+    refine{"refine<br/>estimate in points"} -->|"3 to 5"| implement
     refine -->|"8 or more"| split("Split into children") --> refine
     refine -.->|questions| author
     implement("implement<br/>branch, PR, closes the issue") --> ci("CI")
@@ -110,6 +110,42 @@ Audit creates work rather than consuming it, and files into `refine` rather than
 `implement`, so a report of several unrelated findings becomes one properly sized issue per finding
 instead of one pull request that has to fix them all.
 
+### How a feature stacks
+
+When refine splits a story that carries real sequencing — a feature whose children build on each
+other — the split can open a stack instead of independent work. The children stay ordinary issues
+walking the normal pipeline above; only where they land changes: each child's pull request targets
+the feature branch rather than the default branch, and one root pull request (spec plus the
+feature's acceptance journey, open from the start) carries the whole feature to `main` at the end.
+
+```mermaid
+flowchart TD
+    feat("Feature issue<br/>8+ points, ordered children") --> splitStack("refine split<br/>stamps stack-root-branch + stack-root-pr<br/>on the feature issue") --> rootPr("root pull request on feat/&lt;N&gt;<br/>spec + red journey e2e,<br/>base: main, HELD")
+    splitStack --> child1("child T1: implement<br/>PR base: feat/&lt;N&gt;")
+    child1 --> merge1("merge-gate<br/>auto-merge into feat/&lt;N&gt;<br/>closes T1") --> child2("child T2, T3 ...<br/>same shape, one at a time")
+    child2 --> stacked{"every child landed<br/>and the root is green?"}
+    stacked -.->|"no: a bug found"| fixChild("new child issue<br/>mid-stack insertion") --> child2
+    stacked -->|yes| announce("stack-complete announcement<br/>on the root pull request")
+    announce --> humanStack(("human merges the root<br/>feature issue closes with it"))
+    flat("story with no<br/>sequencing") -.->|"no stack markers:<br/>byte-for-byte the old path"| implement
+
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    class feat,flat start
+    class splitStack,rootPr,child1,merge1,child2,announce,fixChild action
+    class stacked decision
+    class humanStack success
+```
+
+The stack exists only in markers on the issues — `stack-root-branch` and `stack-root-pr` on the
+feature issue, `stack-root-branch` stamped on each child at hand-over — so a repository with none
+of them runs exactly the pipeline above and nothing else. The root is never auto-merged: a person
+merges it after every child has landed and the feature branch is green, which is the point where
+the feature's own acceptance journey, not one child's scope, is the thing being verified.
+
 ---
 
 ## agent-triage.md
@@ -165,7 +201,8 @@ flowchart TD
 ## agent-refine.md
 
 Decides the size of the work, which is the decision that determines whether it ever lands. An
-estimate of 8 or more is split into children of 5 or less, and each child walks the pipeline alone.
+estimate of 8 or more is split into children of 3 to 5 points, and each child walks the pipeline
+alone. A slice smaller than 3 points is a fragment and is folded into a sibling.
 The refined story is wrapped in the repository's own issue form, and when questions remain the
 worker leaves a temporal draft on the issue and asks everything in one batched comment.
 
@@ -188,7 +225,9 @@ flowchart TD
     refSplit -->|no| refOutcome
     refSplit -->|"yes, and it splits"| refChildren
     refSplit -->|"yes, indivisible"| refOutcome
-    refChildren(("Split<br/>2-6 children, each 5 or less<br/>parent becomes their tracker"))
+    refChildren(("Split<br/>2-6 children, each 3 to 5<br/>parent becomes their tracker"))
+    refChildren -->|"children build on each other"| refStack
+    refStack("Stamp stack-root-branch + stack-root-pr<br/>on the feature issue, and open the<br/>held root pull request on feat/&lt;N&gt;") --> refOutcome
     refOutcome{"Questions left<br/>for the author?"}
     refOutcome -->|no| refDone
     refOutcome -->|yes| refAsk
@@ -203,7 +242,7 @@ flowchart TD
     classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class refStart start
-    class refReserve,refFacts,refExplore,refTrivial,refStory,refWrap,refProse action
+    class refReserve,refFacts,refExplore,refTrivial,refStory,refWrap,refProse,refStack action
     class refClassify,refEstimate,refSplit,refOutcome decision
     class refFail failure
     class refDone,refAsk,refChildren success
@@ -242,6 +281,9 @@ flowchart TD
     implIdle(("Idle<br/>closed, or held by future"))
     implFail(("Parked<br/>review added, a rerun<br/>would fail the same way"))
 
+    implStackStart("check-stack-branch<br/>(router job, rung 1)<br/>the issue carries<br/>stack-root-branch?") -.->|"no: flat mode,<br/>nothing happens"| implIdle
+    implStackStart -->|"yes: the workflow dispatches<br/>this worker with ref: feat/N<br/>so the agent never fetches"| implStart
+
     classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
     classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
     classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
@@ -249,7 +291,7 @@ flowchart TD
     classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class implStart start
-    class implReserve,implFacts,implTodos,implCode,implPr action
+    class implReserve,implFacts,implTodos,implCode,implPr,implStackStart action
     class implEligible,implCheck,implVerify,implRetry decision
     class implIdle idle
     class implFail failure
@@ -261,6 +303,13 @@ and that used to burn the issue and hand it to a human. A run that worked for ha
 failed produced an answer that was wrong; repeating it costs the whole fleet the same half hour to
 be wrong again, so only the short deaths are retried.
 
+A stacked child enters the same worker through a different door: the router's `check-stack-branch`
+job reads the issue's markers before anything runs, and dispatches the compiled workflow with
+`ref:` set to the feature branch, because the agent sandbox has no credentials to fetch or choose
+a branch itself. The prompt then tells `create_pull_request` its base: the feature branch for a
+stacked child, the default branch for everything else. Nothing about the standard path above
+changes for an issue without the markers.
+
 ---
 
 ## agent-merge-gate.md
@@ -287,11 +336,14 @@ flowchart TD
     gateProtected -->|"measured low, medium or high"| gateAssess
     gateAssess("Agent (rung 5)<br/>find defects, verify them,<br/>rate recoverability") --> gateDisposition
     gateDisposition{"Disposition<br/>computed in shell from<br/>the facts and the report"}
-    gateDisposition -->|"no verified blocker,<br/>radius low or recoverable medium"| gateMerge
+    gateDisposition -->|"no verified blocker,<br/>radius low or recoverable medium"| gateRootCheck
+    gateRootCheck{"PR base is a<br/>stack feature branch<br/>and this PR is the root?"}
+    gateRootCheck -->|"child PR: no"| gateMerge
     gateDisposition -.->|"radius high, protected<br/>or owner path"| gateOwner
     gateDisposition -.->|"fragile, unmet criteria<br/>or low confidence"| gateHuman
     gateDisposition -.->|"CI red or a verified<br/>high finding"| gateBlocked
-    gateMerge(("AUTO-MERGE<br/>squash, issue closed,<br/>pr-pending removed"))
+    gateMerge(("AUTO-MERGE<br/>squash into the PR's base<br/>(main, or the feature branch:<br/>then the child issue closes,<br/>pr-pending removed)"))
+    gateRootCheck -->|"yes: the root"| gateHeld(("HELD<br/>stack root never auto-merges,<br/>a person merges it once every<br/>child has landed and it is green"))
     gateHuman(("HUMAN REVIEW<br/>review label,<br/>implement label kept"))
     gateOwner(("OWNER REVIEW<br/>review + owner-review,<br/>CODEOWNERS asked when named"))
     gateHuman --> gatePreview
@@ -310,12 +362,20 @@ flowchart TD
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class gateStart start
     class gateBranch,gateFacts,gateFix,gateAssess,gatePreview action
-    class gateSubject,gateCi,gateProtected,gateDisposition decision
+    class gateSubject,gateCi,gateProtected,gateDisposition,gateRootCheck decision
     class gateIdle idle
     class gateHuman,gateOwner,gateBlocked failure
     class gateMerge,gatePush,gateApproved success
 ```
 
+For a child pull request — one whose base is a stack feature branch — everything above is
+unchanged: the risk assessment sees the same diff it always would, and auto-merge means squash
+into the feature branch, closing exactly that child issue. The root pull request is the one
+exception in the whole system: it can be as clean as any merge that ever shipped and the gate
+still will not take it, because a feature is only done when the whole branch is done. AABB holds
+it with an App-token comment and a person takes it from there, after the router's stack-completion
+check has announced that every child landed and the branch is green.
+
 A protected-path match holds the merge but does not stop the repair path: the agent may still fix
 failed CI on those files, and `conclude` is what refuses to merge them.
 
@@ -488,7 +548,16 @@ flowchart TB
     hkRetry --> hkStrand
 
     hkStrand("Strands: drop pr-pending<br/>where no open PR closes the issue") --> hkParent("Close a split parent<br/>once every child is closed")
-    hkParent --> hkBranch{"Branch whose PRs<br/>are all finished<br/>and all bot-authored?"}
+    hkParent --> hkStack{"stack-root-pr<br/>marker on the<br/>feature issue?"}
+    hkStack -.->|"no: flat mode"| hkBranch
+    hkStack -->|"root open"| hkStackWait{"children left,<br/>or the completion<br/>announcement missing?"}
+    hkStackWait -->|"children open: mid-stack,<br/>the normal state"| hkBranch
+    hkStackWait -->|"all landed, never told"| hkDigest
+    hkStackWait -->|"told, but nobody merged for days"| hkDigest
+    hkStack -->|"root merged,<br/>feature issue still open"| hkStackClose("close the feature issue,<br/>close child issues whose<br/>PR merged but stayed open")
+    hkStack -->|"root closed unmerged"| hkDigest
+    hkStackClose --> hkBranch
+    hkBranch{"Branch whose PRs<br/>are all finished<br/>and all bot-authored?"}
     hkBranch -->|yes| hkDelete("Delete the branch")
     hkBranch -.->|"open PR, human PR,<br/>or the default branch"| hkDigest
     hkDelete --> hkDigest
@@ -500,8 +569,8 @@ flowchart TB
     classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class hkCron start
-    class hkScan,hkRetry,hkStrand,hkParent,hkDelete,hkDigest action
-    class hkPark,hkWhy,hkBudget,hkBranch decision
+    class hkScan,hkRetry,hkStrand,hkParent,hkDelete,hkDigest,hkStackClose action
+    class hkPark,hkWhy,hkBudget,hkBranch,hkStack,hkStackWait decision
     class hkEnd success
 ```
 
@@ -512,6 +581,15 @@ would be a green no-op. Every write goes through one `act()` wrapper, which is t
 kinds of issue a split parent whose children are all done, and its own digest which the route
 matrix asserts by counting.
 
+The stack section extends the same two rules to stacked features without adding a third closed
+kind: a merged child whose issue stayed open is closed exactly like a flat split parent (its work
+landed, the close was lost to a race), and a merged root closes the feature issue the same way
+section 3 closes a split parent. Everything else about a stack is a *report*, never an action:
+mid-stack is the normal state and stays silent; a root that finished but was never announced, one
+held for days after its announcement, a root closed by accident with children open, and a missing
+root pull request each get one line in the digest. No labels move, so nothing the router listens
+for is raised by the sweep itself.
+
 ---
 
 ## agentics-app-errors

package/loops/scripts/compile-agent-workflows.mjs

@@ -342,6 +342,13 @@ for (const file of readdirSync(workflowDirectory)) {
   // pull request as an issue instead of a pull request). Checking out the branch tip at
   // execution time makes the commit parent current main; the implement-global queue
   // already keeps sibling merges out of the window while the agent runs.
+  //
+  // A stack child dispatches this workflow directly (`gh workflow run
+  // agent-implement.lock.yml --ref feat/N`), and there the pin must select the feature
+  // branch tip, not main: github.ref_name is the ref the dispatch named. Under
+  // workflow_call the callee inherits the caller's event, and the router is only ever
+  // dispatched on the default branch, so the dispatch arm of the ternary resolves to
+  // main there too -- flat behavior is byte-identical.
   if (file === "agent-implement.lock.yml") {
     const start = rewritten.indexOf("\n  agent:\n");
     const rest = start === -1 ? "" : rewritten.slice(start + 1);
@@ -351,12 +358,56 @@ for (const file of readdirSync(workflowDirectory)) {
       const span = rewritten.slice(start, end).replace(
         /(uses: actions\/checkout@[^\n]*\n(\s+)with:\n(?:\2  [^\n]+\n)*)/,
         (whole, _block, indent) =>
-          whole.includes("ref:") ? whole : whole + indent + "  ref: ${{ github.event.repository.default_branch }}\n",
+          whole.includes("ref:")
+            ? whole
+            : whole +
+              indent +
+              "  ref: ${{ github.event_name == 'workflow_dispatch' && github.ref_name || github.event.repository.default_branch }}\n",
       );
       rewritten = rewritten.slice(0, start) + span + rewritten.slice(end);
     }
   }
 
+  // update_issue declares no required field, so the safe-outputs MCP server accepts a call
+  // carrying only issue_number and answers success. An agent that drops the body - the
+  // documented way is omitting the trailing `.` so the bridge never reads stdin - loses its
+  // whole story, is told nothing, and goes on to claim completion. add_comment declares body
+  // required and rejects the identical mistake, which is how the agent recovers from it on
+  // the next turn. Measured on Lyceum before this: one refine run in five wrote its story,
+  // the other four ended green with the issue untouched (#44, #59 twice, #62), and Numa #698
+  // reached `refined, implement` still carrying its original form body.
+  //
+  // Only agent-refine calls update_issue, and always to replace the body; labels and status
+  // are workflow-owned and the prompt forbids the agent from touching them, so requiring the
+  // body costs no legitimate call. The check below fails the compile if this stops matching.
+  {
+    const toolStart = rewritten.indexOf('"update_issue": {');
+    if (toolStart !== -1) {
+      const bodyField = rewritten.indexOf('"body": {', toolStart);
+      if (bodyField !== -1) {
+        const insertAt = bodyField + '"body": {'.length;
+        if (!rewritten.slice(insertAt, insertAt + 80).includes('"required": true')) {
+          rewritten = rewritten.slice(0, insertAt) + '\n' + ' '.repeat(20) + '"required": true,' + rewritten.slice(insertAt);
+        }
+      }
+    }
+  }
+
+  // The pull request base belongs to the handler, never to the MCP server. agent-implement sets
+  // base-branch from the dispatched ref so a stack child lands on its feature branch, and gh-aw
+  // writes that base into both configs. The safe-outputs MCP server runs inside the sandbox,
+  // where remote refs are not visible, and given a base it insists on a merge-base against
+  // origin/<base>: on Lyceum #73 it answered "No remote refs available for merge-base
+  // calculation" twice and the run died at max-turns with the code already written (run
+  // 38737284343). With no base it patches from the pinned SHA, which the stack dispatch sets to
+  // the feature tip, and that is exactly the patch the handler then applies onto the base. So
+  // the MCP config loses the base and the handler config keeps it. The check below fails the
+  // compile if this stops matching.
+  rewritten = rewritten.replace(
+    /^([ \t]+GH_AW_SAFE_OUTPUTS_CONFIG: "[^\n]*?)\\"base_branch\\":\\"[^\\"]*\\",/m,
+    "$1",
+  );
+
   // Guard the two rewrites the compiled agent jobs cannot work without. The anchors are
   // upstream template text: when a gh-aw upgrade reshapes either step, the silent
   // failure mode returns (an artifact with no bundle, a skipped push, a green gate on
@@ -365,8 +416,31 @@ for (const file of readdirSync(workflowDirectory)) {
     { name: "bundle upload glob", ok: /\n( +)- name: Upload agent artifacts\n\1  if: always\(\)\n\1  continue-on-error: true\n\1  uses: actions\/upload-artifact@[^\n]*\n\1  with:\n\1    name: \$\{\{ needs\.activation\.outputs\.artifact_prefix \}\}agent\n\1    path: \|\n(?:\1      [^\n]*\n)*\1      \/tmp\/gh-aw\/aw-\*\.bundle\n/ },
     { name: "placeholder step intact", ok: /\n( +)- name: Write agent output placeholder if missing\n\1  if: always\(\)\n\1  run: \|\n\1    if \[ ! -f \/tmp\/gh-aw\/agent_output\.json \]; then\n\1      echo '\{"items":\[\]\}' > \/tmp\/gh-aw\/agent_output\.json\n\1    fi\n/ },
     { name: "failed-jobs reporter disabled", ok: /- name: Report failed jobs\n[ \t]*id: report_failed_jobs\n[ \t]*if: false[^\n]*\n/ },
+    // Only agent-refine declares update_issue; the other workers never carry the tool.
+    {
+      name: "update_issue requires a body",
+      ok: lock =>
+        !lock.includes('"update_issue": {') ||
+        /"update_issue": \{[\s\S]{0,3000}?"body": \{\s*\n\s*"required": true,/.test(lock),
+    },
+    // The base reaches the handler and never the MCP server; see the rewrite above. Anchored on
+    // the escaped quotes because allowed_base_branches contains the bare text base_branch.
+    {
+      name: "pull request base stays out of the MCP config",
+      ok: lock => {
+        const mcp = (lock.match(/^[ \t]+GH_AW_SAFE_OUTPUTS_CONFIG: "[^\n]*/m) || [""])[0];
+        const handler = (lock.match(/^[ \t]+GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: "[^\n]*/m) || [""])[0];
+        if (mcp.includes('\\"base_branch\\"')) return false;
+        // The handler config keeps the expression for Actions to expand before the job starts;
+        // only the MCP config is rewritten to an env reference. Either form is the run's ref.
+        return !file.startsWith("agent-implement") ||
+          handler.includes('\\"base_branch\\":\\"${{ github.ref_name }}\\"') ||
+          handler.includes('\\"base_branch\\":\\"${GITHUB_REF_NAME}\\"');
+      },
+    },
   ]) {
-    if (!check.ok.test(rewritten)) {
+    const passed = typeof check.ok === "function" ? check.ok(rewritten) : check.ok.test(rewritten);
+    if (!passed) {
       process.stderr.write(
         `compile patch "${check.name}" no longer matches in ${file}: the gh-aw template changed. ` +
         `Re-anchor the rewrite in loops/scripts/compile-agent-workflows.mjs, or agent pushes are silently dropped.\n`,