@plainconceptsplatform/workflows 0.5.1 → 0.6.1

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

@@ -8,6 +8,9 @@ env:
   REVIEW_LABEL: review
   PR_PENDING_LABEL: pr-pending
   GATE_MARKER: "<!-- agent-merge-gate -->"
+  ATTEMPT_MARKER: "<!-- agent-merge-gate-attempt -->"
+  MAX_ATTEMPTS: "6"
+  PARK_AT_ATTEMPT: "5"
   INCOMPLETE_COMMENT: "Automated CI failure remediation ended without an outcome. The issue remains for a retry."
   ISSUE_CONTEXT_PATH: /tmp/gh-aw/agent/issue-context.json
   GH_AW_ALLOWED_BOTS: "platform-devbox[bot],github-actions[bot]"
@@ -51,6 +54,18 @@ on:
         description: CI workflow run ID for fetching failing logs.
         required: false
         type: string
+      attempts_so_far:
+        description: Failed gate attempts already made against this CI verdict. Parked when it reaches the cap.
+        required: false
+        type: string
+        default: '0'
+  # gh-aw folds the top-level `if:` below into the generated activation job but does not carry
+  # the jobs that `if:` reads into activation's `needs`: only prompt-referenced custom jobs with
+  # no `needs:` of their own are hoisted (subject). protected_changes needs subject, so without
+  # this entry activation read needs.protected_changes.outputs.requires_review before
+  # protected_changes had started; the value was '' and the clause was always true
+  # (Pliny-Bot run 34042143350: activation finished 18 s before protected_changes began).
+  needs: [protected_changes]
 
 # Rung 4. Router has classified the event; identify-gate-subject validates PR ownership,
 # resolves the closing issue, and confirms the CI verdict.
@@ -160,13 +175,17 @@ jobs:
         with:
           client-id: ${{ secrets.BOT_APP_ID }}
           private-key: ${{ secrets.BOT_PRIVATE_KEY }}
+      # Only the reservation comes off. pr-pending says a pull request for this issue is open
+      # and waiting, which is still true when the gate hands it to a human, so taking it off
+      # here left a board where three issues with three open pull requests looked like they
+      # had none. The merge path is the one place the label stops being true.
       - name: Release the issue
         if: needs.protected_changes.outputs.requires_review == 'true' && needs.subject.outputs.conclusion != 'failure'
         uses: ./.github/actions/remove-issue-labels
         with:
           token: ${{ steps.app-token.outputs.token }}
           issue-number: ${{ needs.subject.outputs.issue }}
-          labels: ${{ env.WORKING_LABEL }},${{ env.PR_PENDING_LABEL }}
+          labels: ${{ env.WORKING_LABEL }}
       - name: Flag human review
         if: needs.protected_changes.outputs.requires_review == 'true' && needs.subject.outputs.conclusion != 'failure'
         uses: ./.github/actions/add-issue-labels
@@ -188,6 +207,8 @@ jobs:
             Protected files:
             ${{ needs.protected_changes.outputs.files }}
 
+            **Verdict:** review
+
   reserve:
     needs: subject
     if: needs.subject.outputs.found == 'true'
@@ -223,14 +244,15 @@ jobs:
           else
             echo "has_conflicts=false" >> "$GITHUB_OUTPUT"
           fi
+      # First attempt only. Retries are recorded by the incomplete job's attempt comment, and
+      # every App comment is a router event: one issue collected sixteen of these in a day.
       - name: Comment on issue - problems found, solving them
-        if: needs.subject.outputs.conclusion == 'failure'
+        if: needs.subject.outputs.conclusion == 'failure' && (inputs.attempts_so_far || '0') == '0'
         uses: ./.github/actions/create-issue-comment
         with:
           token: ${{ steps.app-token.outputs.token }}
           issue-number: ${{ needs.subject.outputs.issue }}
           body: |
-            ${{ env.GATE_MARKER }}
             Problems found in PR #${{ needs.subject.outputs.pr }}. ${{ steps.conflicts.outputs.has_conflicts == 'true' && 'Merge conflicts detected.' || 'CI failed.' }}
             Bot is working on fixing it.
   validate_output:
@@ -300,6 +322,20 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
           push-to-branch: 'true'
           apply-labels: 'false'
+      # GITHUB_TOKEN on purpose: an App-token comment on a pull request is an issue_comment
+      # event, and GITHUB_TOKEN raises none. The full assessment lives on the issue, where the
+      # lifecycle is; this is what a reviewer opening the pull request sees. Carrying the
+      # marker and the Verdict line makes the router's verdict detection independent of
+      # whether the model remembered the marker.
+      - name: Show the verdict on the pull request
+        uses: ./.github/actions/create-issue-comment
+        with:
+          token: ${{ github.token }}
+          issue-number: ${{ needs.subject.outputs.pr }}
+          body: |
+            ${{ env.GATE_MARKER }}
+            **Verdict:** ${{ needs.validate_output.outputs.outcome }} (CI concluded ${{ needs.subject.outputs.conclusion }}).
+            Full assessment on the linked issue: #${{ needs.subject.outputs.issue }}. [View this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
       - name: Merge approved pull request
         if: needs.validate_output.outputs.outcome == 'merge'
         env:
@@ -324,20 +360,26 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
           issue-number: ${{ needs.subject.outputs.issue }}
           labels: ${{ env.REVIEW_LABEL }}
+      # The reservation only. The pull request is still open and still waiting, so pr-pending
+      # stays until the merge path below retires it.
       - name: Release review outcome
         if: needs.validate_output.outputs.outcome == 'review'
         uses: ./.github/actions/remove-issue-labels
         with:
           token: ${{ steps.app-token.outputs.token }}
           issue-number: ${{ needs.subject.outputs.issue }}
-          labels: ${{ env.WORKING_LABEL }},${{ env.PR_PENDING_LABEL }}
+          labels: ${{ env.WORKING_LABEL }}
       - name: Clear merged issue labels
         if: needs.validate_output.outputs.outcome == 'merge'
         uses: ./.github/actions/remove-issue-labels
         with:
           token: ${{ steps.app-token.outputs.token }}
           issue-number: ${{ needs.subject.outputs.issue }}
-          labels: ${{ env.IMPLEMENT_LABEL }},${{ env.WORKING_LABEL }},${{ env.REVIEW_LABEL }},${{ env.PR_PENDING_LABEL }}
+          labels: |
+            ${{ env.IMPLEMENT_LABEL }}
+            ${{ env.WORKING_LABEL }}
+            ${{ env.REVIEW_LABEL }}
+            ${{ env.PR_PENDING_LABEL }}
   incomplete:
     needs: [subject, protected_changes, agent, safe_outputs, validate_output]
     if: >
@@ -364,28 +406,52 @@ jobs:
         with:
           client-id: ${{ secrets.BOT_APP_ID }}
           private-key: ${{ secrets.BOT_PRIVATE_KEY }}
-      - name: Release the issue
-        uses: ./.github/actions/remove-issue-labels
+      # The attempt record comes first. The belt bounds its retries by counting attempt comments
+      # newer than the CI verdict, not by labels; releasing the labels before the record existed
+      # meant a failure in either step below un-reserved the issue with nothing to count, and the
+      # belt re-dispatched the same crash every cycle. The steps stay sequential on purpose: an
+      # always() release after a failed park would strip bot-working from an issue that was
+      # meant to be parked with review.
+      # attempts_so_far is a workflow_call input and arrives as '' when the caller passes an
+      # empty expression, declared default or not; fromJson('') is a hard failure, so the empty
+      # case reads as 0.
+      - name: Report the failed attempt
+        if: fromJson(inputs.attempts_so_far || '0') < fromJson(env.PARK_AT_ATTEMPT)
+        uses: ./.github/actions/create-issue-comment
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          issue-number: ${{ needs.subject.outputs.issue }}
+          body: |
+            ${{ env.ATTEMPT_MARKER }}
+            Attempt ${{ inputs.attempts_so_far || '0' }} of ${{ env.MAX_ATTEMPTS }} on PR #${{ needs.subject.outputs.pr }} ended without an outcome.
+            The issue keeps `implement`; the merge belt will retry.
+            [View this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+      - name: Report the exhausted attempt budget
+        if: fromJson(inputs.attempts_so_far || '0') >= fromJson(env.PARK_AT_ATTEMPT)
+        uses: ./.github/actions/create-issue-comment
         with:
           token: ${{ steps.app-token.outputs.token }}
           issue-number: ${{ needs.subject.outputs.issue }}
-          labels: ${{ env.WORKING_LABEL }},${{ env.IMPLEMENT_LABEL }},${{ env.PR_PENDING_LABEL }}
-      - name: Flag for human review
+          body: |
+            ${{ env.ATTEMPT_MARKER }}
+            Attempt ${{ inputs.attempts_so_far || '0' }} of ${{ env.MAX_ATTEMPTS }} on PR #${{ needs.subject.outputs.pr }} ended without an outcome.
+            The attempt budget for this CI verdict is exhausted. The review label is set: a human must take over.
+            [View this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+      - name: Park the issue for a human
+        if: fromJson(inputs.attempts_so_far || '0') >= fromJson(env.PARK_AT_ATTEMPT)
         uses: ./.github/actions/add-issue-labels
         with:
           token: ${{ steps.app-token.outputs.token }}
           issue-number: ${{ needs.subject.outputs.issue }}
           labels: ${{ env.REVIEW_LABEL }}
-      - name: Report missing remediation outcome
-        uses: ./.github/actions/create-issue-comment
+      # The reservation only. A failed attempt does not close the pull request, so pr-pending
+      # is still true and the board should keep saying so.
+      - name: Release the issue
+        uses: ./.github/actions/remove-issue-labels
         with:
           token: ${{ steps.app-token.outputs.token }}
           issue-number: ${{ needs.subject.outputs.issue }}
-          body: |
-            ${{ env.GATE_MARKER }}
-            Bot could not resolve PR #${{ needs.subject.outputs.pr }} automatically. The `review` label is set: a human must take over.
-            ${{ env.INCOMPLETE_COMMENT }}
-            [View this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+          labels: ${{ env.WORKING_LABEL }}
 
   agent:
     # The top-level guard reads both outputs. GitHub Actions does not make a
@@ -424,6 +490,32 @@ checkout:
 # Rung 3. The diff is what the risk assessment reads, and the failing logs are what a fix
 # starts from. Both are known from the inputs, so neither costs the agent a turn.
 steps:
+  # gh-aw checks out the router's ref. Its own "Checkout PR branch" step runs only when the event
+  # carries a pull request, which a router dispatch does not, so the agent would start on main.
+  # apply-agent-output fast-forwards origin/<branch> to the bundle tip and refuses anything else,
+  # and gh-aw builds that bundle from what the agent committed on top of the checkout; both need
+  # the agent to start on the branch it pushes to.
+  - name: Check out the pull request branch
+    env:
+      GH_TOKEN: ${{ github.token }}
+      REPO: ${{ github.repository }}
+      PR: ${{ needs.subject.outputs.pr }}
+    run: |
+      set -euo pipefail
+      branch=$(gh pr view "$PR" --repo "$REPO" --json headRefName --jq '.headRefName')
+      git switch --track "origin/$branch" 2>/dev/null || git switch "$branch"
+      echo "On $(git branch --show-current) at $(git rev-parse --short HEAD)"
+  # Every merge into the default branch invalidates every other open pull request that added a
+  # changelog entry, because they all insert at the top of the same list. The conflict is real
+  # and never interesting: both entries belong, newest first. Without a driver it costs a model
+  # run per sibling pull request, and it recurs on every merge while more than one is in flight.
+  # A consumer opts in by naming its own changelog in .gitattributes with `merge=changelog`;
+  # repositories that do not are unaffected, because git only calls a driver a path asks for.
+  - name: Teach git how to merge a changelog
+    run: |
+      set -euo pipefail
+      git config merge.changelog.name "newest-first changelog entries"
+      git config merge.changelog.driver "node $GITHUB_WORKSPACE/scripts/merge-changelog.mjs %O %A %B"
   - name: Load the issue context
     uses: ./.github/actions/load-issue-context
     with:
@@ -456,6 +548,13 @@ steps:
       fi
 
 safe-outputs:
+  # Path B. Without this, gh-aw's own safe_outputs job writes as well as the conclude job, and
+  # it runs first: it pushed a flattened, single-parent commit with GITHUB_TOKEN while conclude
+  # was still waiting, so the agent's merge commit was lost, the pull request stayed
+  # conflicting, and GITHUB_TOKEN raises no events, so no CI ran on the new head and the belt
+  # stalled (Pliny-Bot run 34051821011). Staged runs everything and writes nothing; conclude
+  # applies the bundle and the comment with the App token, which does start CI.
+  staged: true
   # A failed run is already a red run. An issue per failure buries the real backlog
   # under noise nobody closes.
   report-failure-as-issue: false
@@ -483,6 +582,12 @@ timeout-minutes: 60
    an issue, and that the issue carries `implement`. Do not re-check any of that, and do not
    poll for checks: the conclusion above is the answer.
 
+   You are on the pull request branch. Never rebase, reset, amend or otherwise rewrite
+   history: the workflow applies your commits as a bundle with a fast-forward-only push and
+   discards anything that is not a descendant of the branch tip. The
+   `push_to_pull_request_branch` tool's own description recommends rebasing; in this
+   repository that advice is wrong. Merge, commit, and let the workflow push.
+
 2. Read `${{ env.ISSUE_CONTEXT_PATH }}`. It contains the issue body and its discussion. When
    running `/repo-verify`, the acceptance criteria there define what the implementation must
    satisfy.
@@ -521,13 +626,13 @@ timeout-minutes: 60
 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.
-    Rebase onto `origin/${{ github.event.repository.default_branch }}`
-    (`git rebase origin/${{ github.event.repository.default_branch }}`), resolve every
-    conflict deliberately, 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.
+    Merge `origin/${{ github.event.repository.default_branch }}` into it
+    (`git merge origin/${{ github.event.repository.default_branch }}`), 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.
 
-    Scope verification to the files the rebase touched: pass changed file paths to
+    Scope verification to the files the merge touched: pass changed file paths to
     lint/format tools instead of running them repository-wide (see step 6's scoped
     verification guidance).
 
@@ -535,13 +640,13 @@ timeout-minutes: 60
     ${{ env.VERIFY_COMMANDS }}
     ```
 
-    Push the rebased branch using `push_to_pull_request_branch` (pr_number: ${{ needs.subject.outputs.pr }},
+    Push the merged branch using `push_to_pull_request_branch` (pr_number: ${{ needs.subject.outputs.pr }},
     branch: the current PR branch), then emit the `add_comment` with
     **Verdict:** remediated. CI will re-run on the updated branch and the merge gate
     will be triggered again — the next cycle will see a clean, conflict-free PR and can
     make a proper merge or review decision.
 
-    If the rebase fails or the conflicts are genuinely ambiguous, select the `review`
+    If the merge cannot be completed or the conflicts are genuinely ambiguous, select the `review`
     verdict instead and explain which conflicts could not be resolved safely.
 
     If the conclusion is `success` and `has_conflicts` is `false`, skip this step and
@@ -595,6 +700,15 @@ timeout-minutes: 60
    fix the actual cause. Run these verification commands before a push. Do not weaken a test,
    disable a check, or push an unverified guess.
 
+   **Empty failure evidence is not a reason to ask for review.** If `failed-jobs.json` is `[]`
+   or the logs say they were unavailable, then no CI run judged this head. That is the normal
+   state of a conflicting pull request: GitHub cannot build `refs/pull/N/merge` while the
+   conflict lasts, so no `pull_request` CI can run on it and there is nothing to read. The
+   conflict is the failure to fix. Resolve it as described above, push, and select
+   `remediated`; CI runs on the result and the next cycle gets a real verdict. Select `review`
+   for missing evidence only when `has_conflicts` is `false`, because then there is genuinely
+   nothing to act on.
+
    **Scoped verification.** The commands below are the full suite. This runner has limited
    memory, and a whole-repo lint or build can be killed mid-run. Scope verification to the
    files you actually changed first, and only escalate to the full suite when the scoped run
@@ -699,7 +813,7 @@ flowchart TD
     gateConflict{"Merge conflicts?"}
     gateConflict -->|yes| gateRebase
     gateConflict -->|no| gateTrivial
-    gateRebase("Rebase<br/>Resolve conflicts, /repo-verify") -->|pushed| gateWait
+    gateRebase("Merge main in<br/>Resolve conflicts, /repo-verify") -->|pushed| gateWait
     gateRebase -.->|cannot resolve| gateHuman
     gateTrivial{"Trivial marker?"}
     gateTrivial -->|yes| gateMerge

package/loops/workflows/agent-refine.md

@@ -382,8 +382,16 @@ safe-outputs:
   # under noise nobody closes.
   report-failure-as-issue: false
   threat-detection: false
+  # The refined story replaces the issue body, which is one call carrying the whole
+  # thing. The allowance is three rather than one because a single malformed call the
+  # bridge accepts as spent would otherwise end the run with the body unwritten and a
+  # comment already claiming success: seen on a real run, "the first update_issue call
+  # was sent with an incorrect parameter shape (20 bytes, missing body) and was accepted
+  # with success by the bridge, consuming the 1-per-run quota". The prompt still says to
+  # send the body once.
   update-issue:
     target: "*"
+    max: 3
   add-comment:
   # Split children. An oversized story becomes several implementable ones rather than
   # one issue nobody can land; the cap stops a runaway decomposition.
@@ -391,7 +399,12 @@ safe-outputs:
     max: 6
 
 
-timeout-minutes: 40
+# Sixty rather than forty. A real run wrote the whole refined story and was killed by the
+# clock four short turns later, on its way to submitting it: 36 model turns, most of them
+# under 110 output tokens and still over a minute each, so the budget buys about that many
+# turns whatever the issue is. Not ninety, which is what implement gets for writing code
+# and running a build; this reads a repository and rewrites one issue body.
+timeout-minutes: 60
 ---
 
 1. You are refining the triggering issue **#${{ inputs.issue-number }}**. Do not choose
@@ -553,7 +566,14 @@ timeout-minutes: 40
    them is a domain expert, not an engineer.
 
     **The story is complete.** You answered every exploration question yourself and none remain
-    for the author. Call `update_issue` with the replacement body and `add_comment`
+    for the author.
+
+    Call `update_issue` first, with the replacement body, and wait for it to come back. Send
+    the whole body in that one call: it is the only thing this step has to get right, and a
+    call sent to see what the tool accepts still counts against your allowance even when it
+    fails. Do not send a partial payload, and do not probe.
+
+    Only once that call has succeeded, call `add_comment`
     with `${{ env.REFINE_MARKER }}`, then `${{ env.SAFE_OUTPUT_COMMENT_PREFIX }}`,
     then exactly one of these messages, based only on the `labels` array in the supplied issue
     context:
@@ -561,6 +581,10 @@ timeout-minutes: 40
     - If the array includes the exact label `future`: `Refinement complete. The implement label has been added. Implementation is paused until the future label is removed.`
     - Otherwise: `Refinement complete. The implement label has been added and the implement workflow will start shortly.`
 
+    If `update_issue` did not succeed, do not post either message: an issue that reads as
+    refined with its body untouched is worse than one that says the run failed. Call
+    `report_incomplete` with what the tool told you, and let the run be retried.
+
     **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