@plainconceptsplatform/workflows 0.19.2 → 0.20.1

package/loops/actions/remove-issue-labels/action.yml

@@ -1,37 +1,37 @@
-# Managed by @plainconceptsplatform/workflows. Source: loops/actions/remove-issue-labels/action.yml. Update with workflows update --force; consumer edits may be overwritten.
-name: Remove issue labels
-description: Remove one or more labels from an issue or pull request.
-inputs:
-  token:
-    description: GitHub token used by github-script.
-    required: true
-  issue-number:
-    description: Issue or pull request number.
-    required: true
-  labels:
-    description: Labels to remove, one per line. A comma-separated list is accepted as well.
-    required: true
-runs:
-  using: composite
-  steps:
-    - name: Remove labels
-      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
-      env:
-        ISSUE_NUMBER: ${{ inputs.issue-number }}
-        LABELS: ${{ inputs.labels }}
-      with:
-        github-token: ${{ inputs.token }}
-        script: |
-          // Callers wrote `labels: a,b` while this split on newlines, so one label named "a,b"
-          // was removed: a 404, swallowed below, and neither label ever came off.
-          for (const label of process.env.LABELS.split(/\r?\n|,/).map((label) => label.trim()).filter(Boolean)) {
-            try {
-              await github.rest.issues.removeLabel({
-                ...context.repo,
-                issue_number: Number(process.env.ISSUE_NUMBER),
-                name: label,
-              });
-            } catch (error) {
-              if (error.status !== 404) throw error;
-            }
-          }
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/remove-issue-labels/action.yml. Update with workflows update --force; consumer edits may be overwritten.
+name: Remove issue labels
+description: Remove one or more labels from an issue or pull request.
+inputs:
+  token:
+    description: GitHub token used by github-script.
+    required: true
+  issue-number:
+    description: Issue or pull request number.
+    required: true
+  labels:
+    description: Labels to remove, one per line. A comma-separated list is accepted as well.
+    required: true
+runs:
+  using: composite
+  steps:
+    - name: Remove labels
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        ISSUE_NUMBER: ${{ inputs.issue-number }}
+        LABELS: ${{ inputs.labels }}
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          // Callers wrote `labels: a,b` while this split on newlines, so one label named "a,b"
+          // was removed: a 404, swallowed below, and neither label ever came off.
+          for (const label of process.env.LABELS.split(/\r?\n|,/).map((label) => label.trim()).filter(Boolean)) {
+            try {
+              await github.rest.issues.removeLabel({
+                ...context.repo,
+                issue_number: Number(process.env.ISSUE_NUMBER),
+                name: label,
+              });
+            } catch (error) {
+              if (error.status !== 404) throw error;
+            }
+          }

package/loops/actions/update-agent-issues/action.yml

@@ -1,58 +1,58 @@
-# Managed by @plainconceptsplatform/workflows. Source: loops/actions/update-agent-issues/action.yml. Update with workflows update --force; consumer edits may be overwritten.
-name: Update agent issues
-description: Apply every update_issue item from agent_output.json.
-inputs:
-  output-file:
-    description: Path to agent_output.json.
-    required: true
-  token:
-    description: GitHub token with issues:write.
-    required: true
-  fallback-issue-number:
-    description: Issue an item targets when it names none.
-    required: false
-    default: ''
-runs:
-  using: composite
-  steps:
-    - name: Update issues
-      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
-      env:
-        AGENT_OUTPUT_LIB: ${{ github.action_path }}/../agent-output.cjs
-        OUTPUT_FILE: ${{ inputs.output-file }}
-        FALLBACK_ISSUE_NUMBER: ${{ inputs.fallback-issue-number }}
-      with:
-        github-token: ${{ inputs.token }}
-        script: |
-          const { readAgentItems } = require(process.env.AGENT_OUTPUT_LIB);
-          const items = readAgentItems(process.env.OUTPUT_FILE, 'update_issue');
-
-          let updated = 0;
-
-          for (const item of items) {
-            const target = item.item_number ?? process.env.FALLBACK_ISSUE_NUMBER;
-
-            if (!target) {
-              core.warning(`update_issue item has no item_number and no fallback, skipping: ${JSON.stringify(item)}`);
-              continue;
-            }
-
-            const changes = {};
-            if (item.title) changes.title = item.title;
-            if (item.body) changes.body = item.body;
-
-            if (Object.keys(changes).length === 0) {
-              core.warning(`update_issue item changes nothing, skipping: ${JSON.stringify(item)}`);
-              continue;
-            }
-
-            await github.rest.issues.update({
-              ...context.repo,
-              issue_number: Number(target),
-              ...changes,
-            });
-
-            updated += 1;
-          }
-
-          core.info(`Updated ${updated} issue(s).`);
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/update-agent-issues/action.yml. Update with workflows update --force; consumer edits may be overwritten.
+name: Update agent issues
+description: Apply every update_issue item from agent_output.json.
+inputs:
+  output-file:
+    description: Path to agent_output.json.
+    required: true
+  token:
+    description: GitHub token with issues:write.
+    required: true
+  fallback-issue-number:
+    description: Issue an item targets when it names none.
+    required: false
+    default: ''
+runs:
+  using: composite
+  steps:
+    - name: Update issues
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        AGENT_OUTPUT_LIB: ${{ github.action_path }}/../agent-output.cjs
+        OUTPUT_FILE: ${{ inputs.output-file }}
+        FALLBACK_ISSUE_NUMBER: ${{ inputs.fallback-issue-number }}
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          const { readAgentItems } = require(process.env.AGENT_OUTPUT_LIB);
+          const items = readAgentItems(process.env.OUTPUT_FILE, 'update_issue');
+
+          let updated = 0;
+
+          for (const item of items) {
+            const target = item.item_number ?? process.env.FALLBACK_ISSUE_NUMBER;
+
+            if (!target) {
+              core.warning(`update_issue item has no item_number and no fallback, skipping: ${JSON.stringify(item)}`);
+              continue;
+            }
+
+            const changes = {};
+            if (item.title) changes.title = item.title;
+            if (item.body) changes.body = item.body;
+
+            if (Object.keys(changes).length === 0) {
+              core.warning(`update_issue item changes nothing, skipping: ${JSON.stringify(item)}`);
+              continue;
+            }
+
+            await github.rest.issues.update({
+              ...context.repo,
+              issue_number: Number(target),
+              ...changes,
+            });
+
+            updated += 1;
+          }
+
+          core.info(`Updated ${updated} issue(s).`);

package/loops/actions/validate-merge-gate-output/action.yml

@@ -1,40 +1,62 @@
-# Managed by @plainconceptsplatform/workflows. Source: loops/actions/validate-merge-gate-output/action.yml. Update with workflows update --force; consumer edits may be overwritten.
-name: Validate merge-gate output
-description: Verify agent_output.json contains a usable merge-gate verdict before any state changes.
-inputs:
-  output-file:
-    description: Path to agent_output.json.
-    required: true
-  issue-number:
-    description: Issue number that the merge-gate outcome must target.
-    required: true
-  ci-conclusion:
-    description: CI conclusion supplied to the merge gate.
-    required: true
-outputs:
-  valid:
-    description: Whether the output contains a usable merge-gate comment with a verdict.
-    value: ${{ steps.validate.outputs.valid }}
-  outcome:
-    description: "Deterministic outcome: merge, review, remediated, or invalid."
-    value: ${{ steps.validate.outputs.outcome }}
-runs:
-  using: composite
-  steps:
-    - name: Validate merge-gate outcome
-      id: validate
-      shell: bash
-      env:
-        ISSUE_NUMBER: ${{ inputs.issue-number }}
-        CI_CONCLUSION: ${{ inputs.ci-conclusion }}
-        OUTPUT_FILE: ${{ inputs.output-file }}
-      run: |
-        set -euo pipefail
-
-        outcome="$(bash "${{ github.action_path }}/validate-merge-gate-output.sh" "$OUTPUT_FILE" "$ISSUE_NUMBER" "$CI_CONCLUSION")"
-        echo "outcome=$outcome" >> "$GITHUB_OUTPUT"
-        echo "valid=$([ "$outcome" != 'invalid' ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
-
-        if [ "$outcome" = 'invalid' ]; then
-          echo "::warning::Agent output has no usable merge-gate outcome. It will not be applied."
-        fi
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/validate-merge-gate-output/action.yml. Update with workflows update --force; consumer edits may be overwritten.
+name: Validate merge-gate output
+description: Compute the merge-gate disposition from measured facts and the agent's structured report, before any state changes.
+inputs:
+  output-file:
+    description: Path to agent_output.json.
+    required: true
+  issue-number:
+    description: Issue number that the merge-gate report must target.
+    required: true
+  ci-conclusion:
+    description: CI conclusion supplied to the merge gate.
+    required: true
+  blast-level:
+    description: "Measured blast radius: low, medium or high."
+    required: false
+    default: low
+  protected-hit:
+    description: Whether a protected path was touched.
+    required: false
+    default: 'false'
+  owner-hit:
+    description: Whether an owner path was touched.
+    required: false
+    default: 'false'
+  confidence-threshold:
+    description: Agent confidence below which the pull request goes to a human.
+    required: false
+    default: '0.8'
+outputs:
+  valid:
+    description: Whether the output produced a usable disposition.
+    value: ${{ steps.validate.outputs.valid }}
+  outcome:
+    description: "Disposition: auto-merge, human-review, owner-review, blocked, remediated, or invalid."
+    value: ${{ steps.validate.outputs.outcome }}
+runs:
+  using: composite
+  steps:
+    - name: Compute the merge-gate disposition
+      id: validate
+      shell: bash
+      env:
+        ISSUE_NUMBER: ${{ inputs.issue-number }}
+        CI_CONCLUSION: ${{ inputs.ci-conclusion }}
+        OUTPUT_FILE: ${{ inputs.output-file }}
+        BLAST_LEVEL: ${{ inputs.blast-level }}
+        PROTECTED_HIT: ${{ inputs.protected-hit }}
+        OWNER_HIT: ${{ inputs.owner-hit }}
+        CONFIDENCE_THRESHOLD: ${{ inputs.confidence-threshold }}
+      run: |
+        set -euo pipefail
+
+        outcome="$(bash "${{ github.action_path }}/validate-merge-gate-output.sh" \
+          "$OUTPUT_FILE" "$ISSUE_NUMBER" "$CI_CONCLUSION" \
+          "$BLAST_LEVEL" "$PROTECTED_HIT" "$OWNER_HIT" "$CONFIDENCE_THRESHOLD")"
+        echo "outcome=$outcome" >> "$GITHUB_OUTPUT"
+        echo "valid=$([ "$outcome" != 'invalid' ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
+
+        if [ "$outcome" = 'invalid' ]; then
+          echo "::warning::Agent output has no usable merge-gate report. It will not be applied."
+        fi

package/loops/actions/validate-merge-gate-output/validate-merge-gate-output.sh

@@ -1,46 +1,162 @@
 #!/usr/bin/env bash
 # Managed by @plainconceptsplatform/workflows. Source: loops/actions/validate-merge-gate-output/validate-merge-gate-output.sh. Update with `workflows update --force`; consumer edits may be overwritten.
-# Print the deterministic merge-gate outcome: merge, review, remediated, or invalid.
+# Print the merge-gate disposition: auto-merge, human-review, owner-review, blocked,
+# remediated, or invalid.
+#
+# This file used to read one word out of the agent's prose and call it the decision. It now
+# computes the decision from two sources that cannot be confused with each other: facts the
+# workflow measured before the agent ran (CI, protected and owner paths, blast radius), and
+# structured evidence the agent produced (verified findings, recoverability, confidence). The
+# agent no longer names the outcome. It reports what it found; the rules below decide.
+#
+# The shape rules are strict on purpose. Every permissive default in here is a way for a
+# malformed report to merge code nobody assessed, and the shapes that matter are near misses
+# rather than nonsense: `"verified": "true"` as a string, a severity spelled `blocker`, an
+# `acceptanceCriteriaMet` of `"false"`. Each of those read as the permissive value once. A
+# report that does not match the contract is `invalid`, which parks the pull request; only a
+# report that does match gets to decide anything.
+#
+# Usage:
+#   validate-merge-gate-output.sh OUTPUT_FILE ISSUE CI_CONCLUSION \
+#                                 BLAST_LEVEL PROTECTED_HIT OWNER_HIT CONFIDENCE_THRESHOLD
 
 set -euo pipefail
 
 output_file="$1"
 issue_number="$2"
 ci_conclusion="$3"
+# `${4-low}`, not `${4:-low}`: the colon form substitutes the default for an argument that was
+# passed as an empty string, which is exactly the case that has to be caught. A skipped or
+# failed `protected_changes` reaches this script as empty arguments, and reading those as
+# "low, nothing protected" is how an unmeasured pull request would merge.
+blast_level="${4-low}"
+protected_hit="${5-false}"
+owner_hit="${6-false}"
+confidence_threshold="${7-0.8}"
+
+# An empty measured level is not a low-risk pull request, it is a job that did not report. The
+# defaults above exist for a caller that genuinely has nothing to say; an empty string arriving
+# from a skipped or failed `protected_changes` must not read as the most permissive value.
+[ -n "$blast_level" ] || blast_level=unmeasured
+[ -n "$protected_hit" ] || protected_hit=unmeasured
+[ -n "$owner_hit" ] || owner_hit=unmeasured
+[ -n "$confidence_threshold" ] || confidence_threshold=0.8
 
 if [ ! -f "$output_file" ] || ! jq -e '.items | arrays' "$output_file" >/dev/null 2>&1; then
   echo invalid
   exit 0
 fi
 
-# The agent emits exactly one comment on the source issue. Its verdict tells the
-# workflow which App-token state transition to perform.
-jq -r --arg issue "$issue_number" --arg conclusion "$ci_conclusion" '
-  .items as $items
-  | ($items
-    | [.[] | select(.type == "add_comment" and (.item_number | tostring) == $issue and (.body | type == "string"))]
-    | map(.body |
-        if test("\\*\\*Verdict:\\*\\*\\s*(merge|review|remediated)"; "i") then
-          capture("\\*\\*Verdict:\\*\\*\\s*(?<v>merge|review|remediated)"; "i").v | ascii_downcase
-        else empty end
-      )
-    | .[0] // "invalid") as $outcome
-  | ([$items[] | select(.type == "push_to_pull_request_branch")] | length) as $pushes
-  # remediated used to require conclusion == "failure", which threw correct work away. The prompt
-  # tells the agent to merge main in, verify and push when CI is green but the pull request
-  # conflicts. That is a real and common state: a conflicting pull request has no merge ref, so
-  # GitHub can never run CI on that head, and the belt falls back to the last verdict on the
-  # branch, which is usually success. The agent did the job, the validator called it invalid,
-  # conclude was skipped, and because this worker stages its outputs the resolved merge commit
-  # was discarded. The belt then dispatched again on the same verdict, up to six times, each a
-  # full run on the single-slot merge belt. A push carrying a remediated verdict is remediation
-  # whatever CI last said; what still matters is that exactly one push comes with it.
-  #
-  # No apostrophes in here. This block sits inside the single-quoted jq program, and one
-  # apostrophe closes that string and breaks the script.
-  | if $outcome == "merge" and $conclusion == "success" and $pushes == 0 then "merge"
-    elif $outcome == "remediated" and $pushes == 1 then "remediated"
-    elif $outcome == "review" and $pushes == 0 then "review"
-    else "invalid"
-    end
+# Every jq error becomes `invalid` rather than a non-zero exit. A report shaped so badly that it
+# crashes the program used to fail the step, which skipped `conclude` and left the belt to spend
+# up to six full agent runs on what was a formatting mistake the first time.
+jq -r \
+  --arg issue "$issue_number" \
+  --arg conclusion "$ci_conclusion" \
+  --arg blast "$blast_level" \
+  --arg protected "$protected_hit" \
+  --arg owner "$owner_hit" \
+  --arg threshold "$confidence_threshold" '
+
+  def level_rank: {"low": 0, "medium": 1, "high": 2}[.];
+  def is_bool: type == "boolean";
+  def known_severity: type == "string" and (ascii_downcase | . == "critical" or . == "high" or . == "medium" or . == "low");
+
+  # A finding the rules can act on. Anything else means the report is not the contract, and the
+  # whole report is refused rather than the finding being quietly dropped to the safe side.
+  def well_formed_finding:
+    (has("verified") and (.verified | is_bool))
+    and (has("severity") and (.severity | known_severity));
+
+  def blocks: .verified == true and (.severity | ascii_downcase | . == "critical" or . == "high");
+
+  def decide:
+    .items as $items
+
+    | [$items[] | select(.type == "add_comment"
+        and (.item_number | tostring) == $issue
+        and (.body | type == "string"))] as $comments
+
+    # Exactly one comment may carry a verdict. Taking the first of several let a second comment
+    # reporting a verified critical finding be discarded, and let a comment with no verdict at
+    # all supply the report for a verdict written in another.
+    | [$comments[] | select(.body | test("\\*\\*Verdict:\\*\\*\\s*(assessed|remediated)"; "i"))] as $verdicts
+    | if ($verdicts | length) != 1 then "invalid" else
+
+      ($verdicts[0].body) as $body
+      | ($body | capture("\\*\\*Verdict:\\*\\*\\s*(?<v>assessed|remediated)"; "i").v | ascii_downcase) as $verdict
+      | ([$items[] | select(.type == "push_to_pull_request_branch")] | length) as $pushes
+
+      # The LAST fenced json block in that comment, because the prompt puts the report last and
+      # the prose above it routinely quotes json from the diff under review. Reading the first
+      # fence handed the decision to whatever the agent happened to quote, and PROTECTED_PATHS
+      # names package.json and global.json, so the reviewed diff is often json.
+      | ([$body | scan("```json\\s*(.*?)```"; "m") | .[0]] | last) as $fence
+
+      # remediated used to require conclusion == "failure", which threw correct work away. The
+      # prompt tells the agent to merge main in, verify and push when CI is green but the pull
+      # request conflicts. That is a real and common state: a conflicting pull request has no
+      # merge ref, so GitHub can never run CI on that head, and the belt falls back to the last
+      # verdict on the branch, which is usually success. The agent did the job, the validator
+      # called it invalid, conclude was skipped, and because this worker stages its outputs the
+      # resolved merge commit was discarded. The belt then dispatched again on the same verdict,
+      # up to six times, each a full run on the single-slot merge belt.
+      #
+      # No apostrophes in here. This block sits inside the single-quoted jq program, and one
+      # apostrophe closes that string and breaks the script.
+      | if $verdict == "remediated" and $pushes == 1 then "remediated"
+        elif $verdict != "assessed" or $pushes != 0 then "invalid"
+        elif $fence == null then "invalid"
+        else
+          ($fence | fromjson) as $report
+          | if ($report | type) != "object" then "invalid" else
+
+            ($report.findings // []) as $findings
+            | (($report.blastRadiusRaise // {}) | if type == "object" then (.to // $blast) else null end) as $raise
+
+            # Every field the decision reads is checked before any of it is read. A near miss
+            # here is not a small problem: each one of these used to resolve to the permissive
+            # value and merge.
+            | if ($findings | type) != "array" then "invalid"
+              elif ([$findings[] | select(well_formed_finding | not)] | length) > 0 then "invalid"
+              elif ($report | has("recoverability")) and (($report.recoverability | type != "string") or (($report.recoverability | ascii_downcase) | level_rank) == null) then "invalid"
+              elif ($report | has("acceptanceCriteriaMet")) and (($report.acceptanceCriteriaMet | is_bool) | not) then "invalid"
+              elif ($report | has("confidence")) and (($report.confidence | type) != "number") then "invalid"
+              elif $raise == null or ($raise | type != "string") or (($raise | ascii_downcase) | level_rank) == null then "invalid"
+              elif ($blast | level_rank) == null then "invalid"
+              else
+                ([$findings[] | select(blocks)] | length) as $blockers
+
+                # The agent may raise the measured blast radius when it finds something the path
+                # rules could not see. It may never lower it.
+                | ([($blast | level_rank), ($raise | ascii_downcase | level_rank)] | max) as $level
+
+                # The same rule the findings live by, applied to the one judgement field that
+                # can park a pull request on its own. An unevidenced "low" is the old category
+                # escalation wearing a new name: replayed against a consumer, a model that rated
+                # everything low dropped the auto-merge rate straight back to 27%, which is
+                # where it started. Saying a change cannot be undone means naming what cannot.
+                | (($report.recoverability // "medium") | ascii_downcase) as $claimed
+                | ((($report.recoverabilitySignals // []) | (type == "array") and (length > 0))) as $evidenced
+                | (if $claimed == "low" and ($evidenced | not) then "medium" else $claimed end) as $recoverability
+                | (($report.confidence // 0)) as $confidence
+
+                | if $conclusion != "success" then "blocked"
+                  elif $blockers > 0 then "blocked"
+                  elif $protected == "true" or $owner == "true" or $level == 2 then "owner-review"
+                  # A fact the workflow could not measure is not a fact. Anything other than a
+                  # clean true or false here means protected_changes did not report, and the
+                  # pull request goes to a person rather than through on a default.
+                  elif $protected != "false" or $owner != "false" then "human-review"
+                  elif $level == 1 and $recoverability == "low" then "human-review"
+                  elif ($report | has("acceptanceCriteriaMet")) and $report.acceptanceCriteriaMet == false then "human-review"
+                  elif $confidence < ($threshold | tonumber) then "human-review"
+                  else "auto-merge"
+                  end
+              end
+            end
+        end
+      end;
+
+  try decide catch "invalid"
 ' "$output_file"

package/loops/actions/validate-refine-output/action.yml

@@ -1,44 +1,48 @@
-# Managed by @plainconceptsplatform/workflows. Source: loops/actions/validate-refine-output/action.yml. Update with workflows update --force; consumer edits may be overwritten.
-name: Validate refine output
-description: Verify agent_output.json contains a usable refinement outcome before any GitHub writes.
-inputs:
-  output-file:
-    description: Path to agent_output.json.
-    required: true
-  marker:
-    description: Comment marker removed before evaluating clarification content.
-    required: true
-  comment-prefix:
-    description: Comment prefix removed before evaluating clarification content.
-    required: true
-  issue-number:
-    description: Issue number that every refinement outcome must target.
-    required: true
-outputs:
-  valid:
-    description: Whether the output contains a usable replacement body or clarification comment.
-    value: ${{ steps.validate.outputs.valid }}
-  outcome:
-    description: "Deterministic refinement outcome: complete, questions, or invalid."
-    value: ${{ steps.validate.outputs.outcome }}
-runs:
-  using: composite
-  steps:
-    - name: Validate refinement outcome
-      id: validate
-      shell: bash
-      env:
-        COMMENT_PREFIX: ${{ inputs.comment-prefix }}
-        ISSUE_NUMBER: ${{ inputs.issue-number }}
-        MARKER: ${{ inputs.marker }}
-        OUTPUT_FILE: ${{ inputs.output-file }}
-      run: |
-        set -euo pipefail
-
-        outcome="$(bash "${{ github.action_path }}/validate-refine-output.sh" "$OUTPUT_FILE" "$MARKER" "$COMMENT_PREFIX" "$ISSUE_NUMBER")"
-        echo "outcome=$outcome" >> "$GITHUB_OUTPUT"
-        echo "valid=$([ "$outcome" != 'invalid' ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
-
-        if [ "$outcome" = 'invalid' ]; then
-          echo "::warning::Agent output has no usable refinement outcome. It will not be applied."
-        fi
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/validate-refine-output/action.yml. Update with workflows update --force; consumer edits may be overwritten.
+name: Validate refine output
+description: Verify agent_output.json contains a usable refinement outcome before any GitHub writes.
+inputs:
+  output-file:
+    description: Path to agent_output.json.
+    required: true
+  marker:
+    description: Comment marker removed before evaluating clarification content.
+    required: true
+  draft-marker:
+    description: Marker that identifies a temporal draft body written while questions remain.
+    required: true
+  comment-prefix:
+    description: Comment prefix removed before evaluating clarification content.
+    required: true
+  issue-number:
+    description: Issue number that every refinement outcome must target.
+    required: true
+outputs:
+  valid:
+    description: Whether the output contains a usable replacement body or clarification comment.
+    value: ${{ steps.validate.outputs.valid }}
+  outcome:
+    description: "Deterministic refinement outcome: complete, split, questions, or invalid."
+    value: ${{ steps.validate.outputs.outcome }}
+runs:
+  using: composite
+  steps:
+    - name: Validate refinement outcome
+      id: validate
+      shell: bash
+      env:
+        COMMENT_PREFIX: ${{ inputs.comment-prefix }}
+        DRAFT_MARKER: ${{ inputs.draft-marker }}
+        ISSUE_NUMBER: ${{ inputs.issue-number }}
+        MARKER: ${{ inputs.marker }}
+        OUTPUT_FILE: ${{ inputs.output-file }}
+      run: |
+        set -euo pipefail
+
+        outcome="$(bash "${{ github.action_path }}/validate-refine-output.sh" "$OUTPUT_FILE" "$MARKER" "$COMMENT_PREFIX" "$ISSUE_NUMBER" "$DRAFT_MARKER")"
+        echo "outcome=$outcome" >> "$GITHUB_OUTPUT"
+        echo "valid=$([ "$outcome" != 'invalid' ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
+
+        if [ "$outcome" = 'invalid' ]; then
+          echo "::warning::Agent output has no usable refinement outcome. It will not be applied."
+        fi

package/loops/actions/validate-refine-output/validate-refine-output.sh

@@ -8,13 +8,14 @@ output_file="$1"
 marker="$2"
 comment_prefix="$3"
 issue_number="$4"
+draft_marker="$5"
 
 if [ ! -f "$output_file" ] || ! jq -e '.items | arrays' "$output_file" >/dev/null 2>&1; then
   echo invalid
   exit 0
 fi
 
-jq -r --arg marker "$marker" --arg prefix "$comment_prefix" --arg issue "$issue_number" '
+jq -r --arg marker "$marker" --arg prefix "$comment_prefix" --arg issue "$issue_number" --arg draft_marker "$draft_marker" '
   def has_replacement_body:
     any(.items[]; .type == "update_issue" and
       (.item_number == null or (.item_number | tostring) == $issue) and
@@ -23,6 +24,14 @@ jq -r --arg marker "$marker" --arg prefix "$comment_prefix" --arg issue "$issue_
   def has_update:
     any(.items[]; .type == "update_issue");
 
+  # A temporal draft is a replacement body the worker still expects to grow: the draft
+  # marker distinguishes it from a finished body.
+  def has_draft_body:
+    any(.items[]; .type == "update_issue" and
+      (.item_number == null or (.item_number | tostring) == $issue) and
+      (.body | type == "string") and
+      (.body | contains($draft_marker)));
+
   # A split writes children, which are the only items allowed to target something other than
   # the source issue: they do not exist yet, so they carry no number at all.
   def child_count:
@@ -65,11 +74,13 @@ jq -r --arg marker "$marker" --arg prefix "$comment_prefix" --arg issue "$issue_
 
   # Order matters: a run that wrote children is a split even though it also replaced the
   # parent body, and a lone child with no parent update is an incomplete split, not a
-  # complete refinement.
+  # complete refinement. A body carrying the draft marker is a temporal draft, not a
+  # finished refinement: it only counts as the questions outcome when the matching
+  # batched-questions comment is also there.
   if child_count >= 2 and has_replacement_body and has_only_source_items then "split"
   elif child_count > 0 then "invalid"
-  elif has_replacement_body and has_only_source_items then "complete"
-  elif has_clarification and (has_update | not) and has_only_source_items
+  elif has_replacement_body and (has_draft_body | not) and has_only_source_items then "complete"
+  elif has_clarification and ((has_update | not) or has_draft_body) and has_only_source_items
     and (reported_incomplete | not) then "questions"
   else "invalid"
   end