@plainconceptsplatform/workflows 0.4.34 → 0.5.1

package/README.md

@@ -1,88 +1,88 @@
-# Workflows CLI
-
-Install and update shared GitHub Agentic Workflows for Plain Concepts Platform repositories.
-
-## Quick start
-
-The primary entrypoint is the interactive TUI. Run it with no arguments:
-
-```bash
-npx @plainconceptsplatform/workflows
-```
-
-The TUI lists all routes and templates with install status. Arrow keys navigate, space toggles, Enter installs. Selecting routes installs only those route workers plus mandatory files (opencode.ci.json, compile script, shared imports, actions, router, classifier, route matrix). Selecting only templates installs just those templates.
-
-## Install
-
-Before installing workflows, install and configure [`PlainConceptsPlatform/agent-harness`](https://github.com/PlainConceptsPlatform/agent-harness) in the consumer repository. Loop workers invoke the skills and commands it provides. Verify the required skills and commands are available before compiling workflows.
-
-For non-interactive use (advanced):
-
-```bash
-npx @plainconceptsplatform/workflows@latest init
-npx @plainconceptsplatform/workflows@latest add
-npx @plainconceptsplatform/workflows@latest update
-```
-
-For a project-local development dependency:
-
-```bash
-pnpm add -D @plainconceptsplatform/workflows
-pnpm exec workflows              # launch interactive TUI
-pnpm exec workflows init
-pnpm exec workflows add
-```
-
-`init` inspects the repository and reports its stack and visibility. It does not create or manage repository configuration or a manifest.
-
-`add` installs mandatory files (opencode.ci.json, compile script, shared imports, actions, router, classifier, route matrix) when called with no route arguments. Pass route names as positional arguments to install specific route workers alongside the mandatory files:
-
-```bash
-workflows add                        # mandatory files only, no worker .md files
-workflows add implement refine direct  # those route workers plus mandatory files
-workflows add --template agentics-checks  # named template only (no mandatory files)
-workflows add refine --template agentics-checks --force  # routes + template + mandatory, overwriting conflicts
-```
-
-Route names: refine, implement, direct, apply-review, merge-gate, audit, propose. Unknown arguments produce an error.
-
-Use `workflows update --force` to force-overwrite managed files that differ from the package source.
-
-Install optional standalone templates with `add --template`. Available templates are `agentics-checks`, `agentics-maintenance`, `app-ci-dotnet-next`, `app-ci-node-monorepo`, and `github-release`. CI templates are stack-specific copies, not a combined template. `github-release` publishes generated release notes when a `v*` tag is pushed. Edit their top-level `env:` values for repository paths, package names, and commands.
-
-## List and search
-
-List all available workflows, routes, and templates with install status:
-
-```bash
-npx --yes --package @plainconceptsplatform/workflows@latest workflows list
-```
-
-Each entry is marked `[x]` when the corresponding `.github/workflows/agent-*.md` file already exists in the current directory, or `[ ]` when it is not yet installed.
-
-Search by name or description:
-
-```bash
-npx --yes --package @plainconceptsplatform/workflows@latest workflows search "ci"
-```
-
-## Manual installation
-
-The package includes `loops/`, a copyable equivalent of `.github/`:
-
-- `loops/actions/` maps to `.github/actions/`
-- `loops/workflows/` maps to `.github/workflows/`
-- `loops/scripts/` maps to `scripts/`
-
-Copy these files manually if you do not use the CLI. Each worker is self-contained. Edit its
-top-level `env:` defaults directly for consumer-specific endpoint, model, labels, paths, and checks.
-
-## Compile
-
-Consumer repositories generate and commit `*.lock.yml` files:
-
-```bash
-node scripts/compile-agent-workflows.mjs --force
-```
-
-Do not commit generated locks to this package source repository.
+# Workflows CLI
+
+Install and update shared GitHub Agentic Workflows for Plain Concepts Platform repositories.
+
+## Quick start
+
+The primary entrypoint is the interactive TUI. Run it with no arguments:
+
+```bash
+npx @plainconceptsplatform/workflows
+```
+
+The TUI lists all routes and templates with install status. Arrow keys navigate, space toggles, Enter installs. Selecting routes installs only those route workers plus mandatory files (opencode.ci.json, compile script, shared imports, actions, router, classifier, route matrix). Selecting only templates installs just those templates.
+
+## Install
+
+Before installing workflows, install and configure [`PlainConceptsPlatform/agent-harness`](https://github.com/PlainConceptsPlatform/agent-harness) in the consumer repository. Loop workers invoke the skills and commands it provides. Verify the required skills and commands are available before compiling workflows.
+
+For non-interactive use (advanced):
+
+```bash
+npx @plainconceptsplatform/workflows@latest init
+npx @plainconceptsplatform/workflows@latest add
+npx @plainconceptsplatform/workflows@latest update
+```
+
+For a project-local development dependency:
+
+```bash
+pnpm add -D @plainconceptsplatform/workflows
+pnpm exec workflows              # launch interactive TUI
+pnpm exec workflows init
+pnpm exec workflows add
+```
+
+`init` inspects the repository and reports its stack and visibility. It does not create or manage repository configuration or a manifest.
+
+`add` installs mandatory files (opencode.ci.json, compile script, shared imports, actions, router, classifier, route matrix) when called with no route arguments. Pass route names as positional arguments to install specific route workers alongside the mandatory files:
+
+```bash
+workflows add                        # mandatory files only, no worker .md files
+workflows add implement refine direct  # those route workers plus mandatory files
+workflows add --template agentics-checks  # named template only (no mandatory files)
+workflows add refine --template agentics-checks --force  # routes + template + mandatory, overwriting conflicts
+```
+
+Route names: refine, implement, direct, apply-review, merge-gate, audit, propose. Unknown arguments produce an error.
+
+Use `workflows update --force` to force-overwrite managed files that differ from the package source.
+
+Install optional standalone templates with `add --template`. Available templates are `agentics-checks`, `agentics-maintenance`, `app-ci-dotnet-next`, `app-ci-node-monorepo`, and `github-release`. CI templates are stack-specific copies, not a combined template. `github-release` publishes generated release notes when a `v*` tag is pushed. Edit their top-level `env:` values for repository paths, package names, and commands.
+
+## List and search
+
+List all available workflows, routes, and templates with install status:
+
+```bash
+npx --yes --package @plainconceptsplatform/workflows@latest workflows list
+```
+
+Each entry is marked `[x]` when the corresponding `.github/workflows/agent-*.md` file already exists in the current directory, or `[ ]` when it is not yet installed.
+
+Search by name or description:
+
+```bash
+npx --yes --package @plainconceptsplatform/workflows@latest workflows search "ci"
+```
+
+## Manual installation
+
+The package includes `loops/`, a copyable equivalent of `.github/`:
+
+- `loops/actions/` maps to `.github/actions/`
+- `loops/workflows/` maps to `.github/workflows/`
+- `loops/scripts/` maps to `scripts/`
+
+Copy these files manually if you do not use the CLI. Each worker is self-contained. Edit its
+top-level `env:` defaults directly for consumer-specific endpoint, model, labels, paths, and checks.
+
+## Compile
+
+Consumer repositories generate and commit `*.lock.yml` files:
+
+```bash
+node scripts/compile-agent-workflows.mjs --force
+```
+
+Do not commit generated locks to this package source repository.

package/loops/actions/agent-output.cjs

@@ -1,17 +1,17 @@
-// Managed by @plainconceptsplatform/workflows. Source: loops/actions/agent-output.cjs. Update with `workflows update --force`; consumer edits may be overwritten.
-const fs = require('node:fs');
-
-// Every apply-agent-* action reads the same artifact the same way: a missing file means the
-// agent produced nothing, which is a normal outcome rather than a failure.
-function readAgentItems(outputFile, type) {
-  if (!outputFile || !fs.existsSync(outputFile)) {
-    return [];
-  }
-
-  const parsed = JSON.parse(fs.readFileSync(outputFile, 'utf8'));
-  const items = Array.isArray(parsed.items) ? parsed.items : [];
-
-  return type ? items.filter((item) => item.type === type) : items;
-}
-
-module.exports = { readAgentItems };
+// Managed by @plainconceptsplatform/workflows. Source: loops/actions/agent-output.cjs. Update with `workflows update --force`; consumer edits may be overwritten.
+const fs = require('node:fs');
+
+// Every apply-agent-* action reads the same artifact the same way: a missing file means the
+// agent produced nothing, which is a normal outcome rather than a failure.
+function readAgentItems(outputFile, type) {
+  if (!outputFile || !fs.existsSync(outputFile)) {
+    return [];
+  }
+
+  const parsed = JSON.parse(fs.readFileSync(outputFile, 'utf8'));
+  const items = Array.isArray(parsed.items) ? parsed.items : [];
+
+  return type ? items.filter((item) => item.type === type) : items;
+}
+
+module.exports = { readAgentItems };

package/loops/actions/audit-close/action.yml

@@ -81,6 +81,30 @@ runs:
               ? 'This report references no issues.'
               : `All ${closedRefs} referenced issue(s) are closed.`;
 
+            // Do not close if there are open PRs that close this issue.
+            // The audit report may have spawned implement workers whose PRs
+            // are still under review — closing the report prematurely is misleading.
+            const openPRs = await github.paginate(github.rest.pulls.list, {
+              ...context.repo,
+              state: 'open',
+              per_page: 100,
+            });
+
+            const closesThisReport = openPRs.some((pr) => {
+              const body = pr.body ?? '';
+              const patterns = [
+                new RegExp(`(?:^|[^A-Za-z0-9_/])#(?:closes?|fixes?|resolves?|closed?)\\s+#${report.number}\\b`, 'i'),
+                new RegExp(`(?:^|[^A-Za-z0-9_/])#${report.number}\\b`),
+              ];
+              return patterns.some((p) => p.test(body));
+            });
+
+            if (closesThisReport) {
+              core.info(`#${report.number}: kept open, has open PR(s) that close it.`);
+              keptOpen += 1;
+              continue;
+            }
+
             await github.rest.issues.createComment({
               ...context.repo,
               issue_number: report.number,

package/loops/actions/classify-route/action.yml

@@ -27,9 +27,6 @@ outputs:
   refine-mode:
     description: first or rerefine.
     value: ${{ steps.classify.outputs.refine-mode }}
-  direct-mode:
-    description: first or continue.
-    value: ${{ steps.classify.outputs.direct-mode }}
   triage-mode:
     description: first or retriage.
     value: ${{ steps.classify.outputs.triage-mode }}
@@ -47,6 +44,7 @@ runs:
         ACTION: ${{ github.event.action }}
         LABEL: ${{ github.event.label.name }}
         ISSUE_LABELS: ${{ toJSON(github.event.issue.labels.*.name) }}
+        ISSUE_STATE: ${{ github.event.issue.state }}
         EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
         EVENT_PR_NUMBER: ${{ github.event.pull_request.number }}
         COMMENT_ON_PR: ${{ github.event.issue.pull_request != '' }}

package/loops/actions/classify-route/classify-route.sh

@@ -11,11 +11,7 @@ set -euo pipefail
 readonly AUDIT_CRON="17 1 * * 1"
 readonly AUDIT_CLOSE_CRON="43 3 * * *"
 readonly CLEANUP_ARTIFACTS_CRON="0 6 * * *"
-readonly RECONCILE_BOT_PR_RUNS_CRON="17 */2 * * *"
-# Daily, but it proposes far less often than daily: the worker holds one open
-# proposal at a time and skips while that slot is filled. The cron is a heartbeat,
-# the queue is the pacing.
-readonly PROPOSE_CRON="29 7 * * *"
+readonly RECONCILE_BOT_PR_RUNS_CRON="17 * * * *"
 
 has_label() {
   jq -e --arg name "$1" 'index($name)' >/dev/null 2>&1 <<<"${ISSUE_LABELS:-[]}"
@@ -28,17 +24,27 @@ is_issue_number() {
 classify_route() {
   local route="none" error=""
   local issue_number="" pr_number="" ci_conclusion="" ci_run_id=""
-  local refine_mode="" direct_mode="" triage_mode="" trigger_kind=""
+  local refine_mode="" triage_mode="" trigger_kind=""
 
   case "${EVENT:-}" in
     issues)
-      if [ "${ACTION:-}" = "opened" ]; then
-        # Issue opened by an outside collaborator → triage. The authorize job
-        # gates the caller on is_outside_collaborator; this routes unconditionally
-        # so write+ openers classify to triage but the caller job skips them.
-        route="triage"
-        triage_mode="first"
-        issue_number="${EVENT_ISSUE_NUMBER:-}"
+      # A closed issue is finished work, but label edits on one still arrive as events.
+      if [ "${ISSUE_STATE:-}" = "closed" ]; then
+        error="issue is closed"
+      elif [ "${ACTION:-}" = "opened" ]; then
+        # Issue opened with a work label → skip triage.
+        # The label event will trigger authorize-bot-work → bot-working → the
+        # correct worker. Triage would only interfere.
+        if has_label refine || has_label implement; then
+          error="issue opened with a work label; triage skipped"
+        else
+          # Issue opened by an outside collaborator → triage. The authorize job
+          # gates the caller on is_outside_collaborator; this routes unconditionally
+          # so write+ openers classify to triage but the caller job skips them.
+          route="triage"
+          triage_mode="first"
+          issue_number="${EVENT_ISSUE_NUMBER:-}"
+        fi
       elif [ "${ACTION:-}" = "labeled" ]; then
         case "${LABEL:-}" in
           bot-working)
@@ -53,12 +59,8 @@ classify_route() {
               route="refine"
               refine_mode="first"
               issue_number="${EVENT_ISSUE_NUMBER:-}"
-            elif has_label direct; then
-              route="direct"
-              direct_mode="first"
-              issue_number="${EVENT_ISSUE_NUMBER:-}"
             else
-              error="bot-working added but no work label (implement/refine/direct) found"
+              error="bot-working added but no work label found"
             fi
             ;;
           triage)
@@ -75,7 +77,7 @@ classify_route() {
               triage_mode="first"
             fi
             ;;
-          refine | implement | direct)
+          refine | implement)
             # If the actor is a bot (e.g. refine→implement transition), route directly.
             # If the actor is a human, authorize-bot-work.yml will add bot-working which triggers the workflow.
             if [ "${ACTOR:-}" != "" ] && echo "${ACTOR:-}" | grep -q '\[bot\]$'; then
@@ -83,13 +85,11 @@ classify_route() {
               issue_number="${EVENT_ISSUE_NUMBER:-}"
               if [ "${LABEL:-}" = "refine" ]; then
                 refine_mode="first"
-              elif [ "${LABEL:-}" = "direct" ]; then
-                direct_mode="first"
               fi
             elif has_label bot-working; then
               # Already has bot-working - the workflow is already running or queued.
               # Don't re-trigger.
-              error="issue already has bot-working label; implement/refine/direct already in progress"
+              error="issue already has bot-working label; implement/refine already in progress"
             else
               error="waiting for bot to add bot-working label"
             fi
@@ -102,6 +102,10 @@ classify_route() {
       if [ "${COMMENT_ON_PR:-false}" = "true" ]; then
         route="apply-review"
         pr_number="${EVENT_ISSUE_NUMBER:-}"
+      elif [ "${ISSUE_STATE:-}" = "closed" ]; then
+        # A closing comment on a refine-labelled issue used to start a full re-refine, which
+        # held a runner for 35 minutes and filed split children under an already-shut parent.
+        error="issue is closed"
       elif [ "${COMMENT_SENDER_TYPE:-}" = "Bot" ]; then
         error="comment authored by a bot"
       elif has_label triage; then
@@ -110,12 +114,8 @@ classify_route() {
         issue_number="${EVENT_ISSUE_NUMBER:-}"
       elif has_label implement; then
         error="issue has implement label; comments do not re-trigger implement"
-      elif has_label direct; then
-        route="direct"
-        direct_mode="continue"
-        issue_number="${EVENT_ISSUE_NUMBER:-}"
       elif ! has_label refine; then
-        error="issue does not carry the refine or direct label"
+        error="issue does not carry the refine label"
       else
         route="refine"
         refine_mode="rerefine"
@@ -143,10 +143,15 @@ classify_route() {
       ;;
 
     workflow_run)
-      if is_issue_number "${RUN_PR_NUMBER:-}"; then
+      # Only a FAILED CI run on an attached pull request auto-dispatches the gate. A green
+      # run reaches merge through app-ci's dispatch-merge-gate and the reconcile belt, so
+      # routing success here would double-fire the gate for every passing pull request.
+      if [ "${RUN_CONCLUSION:-}" != "failure" ]; then
+        error="CI concluded '${RUN_CONCLUSION:-}'; the gate auto-triggers only on failure"
+      elif is_issue_number "${RUN_PR_NUMBER:-}"; then
         route="merge-gate"
         pr_number="${RUN_PR_NUMBER}"
-        ci_conclusion="${RUN_CONCLUSION:-}"
+        ci_conclusion="failure"
         ci_run_id="${RUN_ID:-}"
       else
         error="CI run has no attached pull request"
@@ -167,14 +172,12 @@ classify_route() {
     workflow_dispatch)
       trigger_kind="manual"
       case "${OPERATION:-}" in
-        refine | implement | direct)
+        refine | implement)
           if is_issue_number "${INPUT_ISSUE_NUMBER:-}"; then
             route="${OPERATION}"
             issue_number="${INPUT_ISSUE_NUMBER}"
             if [ "$OPERATION" = "refine" ]; then
               refine_mode="${INPUT_MODE:-first}"
-            elif [ "$OPERATION" = "direct" ]; then
-              direct_mode="${INPUT_MODE:-first}"
             fi
           else
             error="operation '${OPERATION}' needs a positive issue-number, got '${INPUT_ISSUE_NUMBER:-}'"
@@ -207,13 +210,16 @@ classify_route() {
             error="operation 'merge-gate' needs a positive pr-number, got '${INPUT_PR_NUMBER:-}'"
           fi
           ;;
-        audit | propose)
+        audit)
           route="${OPERATION}"
           trigger_kind="${INPUT_TRIGGER_KIND:-manual}"
           ;;
-          audit-close | cleanup-artifacts | reconcile-bot-pr-runs | validate)
+        audit-close | cleanup-artifacts | reconcile-bot-pr-runs | validate)
           route="${OPERATION}"
           ;;
+        release)
+          route="release"
+          ;;
         *)
           error="unknown operation '${OPERATION:-}'"
           ;;
@@ -232,7 +238,6 @@ pr-number=${pr_number}
 ci-conclusion=${ci_conclusion}
 ci-run-id=${ci_run_id}
 refine-mode=${refine_mode}
-direct-mode=${direct_mode}
 triage-mode=${triage_mode}
 trigger-kind=${trigger_kind}
 error=${error}

package/loops/actions/update-changelog/action.yml

@@ -0,0 +1,113 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/update-changelog/action.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+name: Update changelog
+description: Prepend a changelog entry for a landed issue and push it to the default branch.
+
+inputs:
+  token:
+    description: Token with contents write on the repository.
+    required: true
+  issue-number:
+    description: Issue the landed commit implements.
+    required: true
+  commit-sha:
+    description: Commit the work landed as. Its subject becomes the summary.
+    required: true
+  changelog-path:
+    description: Path to changelog.json.
+    required: false
+    default: apps/web/src/shared/data/changelog.json
+  max-entries:
+    description: Newest entries to keep.
+    required: false
+    default: "20"
+
+runs:
+  using: composite
+  steps:
+    - name: Prepend the entry and push
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        REPO: ${{ github.repository }}
+        ISSUE_NUMBER: ${{ inputs.issue-number }}
+        COMMIT_SHA: ${{ inputs.commit-sha }}
+        CHANGELOG_PATH: ${{ inputs.changelog-path }}
+        MAX_ENTRIES: ${{ inputs.max-entries }}
+        DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+      run: |
+        set -euo pipefail
+
+        # This used to be part of the implement prompt. It is deterministic work, and leaving it
+        # to the agent made every implement touch the same file: two runs whose branches were cut
+        # before the other merged conflicted here, produced correct code, and still failed to open
+        # a pull request. Doing it after the merge means exactly one writer, always against a
+        # current default branch.
+
+        host="${GITHUB_SERVER_URL#https://}"
+        git config user.name "github-actions[bot]"
+        git config user.email "github-actions[bot]@users.noreply.github.com"
+        git remote set-url origin "https://x-access-token:${GH_TOKEN}@${host}/${GITHUB_REPOSITORY}.git"
+
+        git fetch --quiet origin "$DEFAULT_BRANCH"
+        git checkout --quiet -B "$DEFAULT_BRANCH" "origin/$DEFAULT_BRANCH"
+
+        if [ ! -f "$CHANGELOG_PATH" ]; then
+          echo "::notice::$CHANGELOG_PATH does not exist; nothing to update."
+          exit 0
+        fi
+
+        # Idempotent: a re-run, a retry, or a second call for the same commit must not add a
+        # duplicate row.
+        short_sha="${COMMIT_SHA:0:7}"
+        if jq -e --arg c "$short_sha" '.changes[]? | select(.commit == $c)' "$CHANGELOG_PATH" >/dev/null 2>&1; then
+          echo "::notice::$short_sha is already in the changelog."
+          exit 0
+        fi
+
+        title=$(gh issue view "$ISSUE_NUMBER" --repo "$REPO" --json title --jq '.title')
+
+        # The commit subject carries what actually changed. Strip the conventional-commit prefix
+        # and the trailing issue reference so the summary reads as prose rather than as a commit.
+        subject=$(git log -1 --format=%s "$COMMIT_SHA")
+        summary=$(printf '%s' "$subject" \
+          | sed -E 's/^[a-z]+(\([^)]*\))?!?: *//' \
+          | sed -E 's/ *\(#[0-9]+\) *$//')
+        [ -n "$summary" ] || summary="$title"
+        # Capitalise, because a commit subject conventionally starts lowercase and this is read
+        # by people rather than by tooling.
+        summary="$(printf '%s' "${summary:0:1}" | tr '[:lower:]' '[:upper:]')${summary:1}"
+
+        timestamp=$(git log -1 --format=%cI "$COMMIT_SHA")
+
+        tmp=$(mktemp)
+        jq --argjson n "$MAX_ENTRIES" \
+           --arg ts "$timestamp" \
+           --argjson issue "$ISSUE_NUMBER" \
+           --arg title "$title" \
+           --arg summary "$summary" \
+           --arg commit "$short_sha" \
+           '.changes = ([{timestamp: $ts, issue: $issue, title: $title, summary: $summary, commit: $commit}] + (.changes // []))[:$n]' \
+           "$CHANGELOG_PATH" > "$tmp"
+        mv "$tmp" "$CHANGELOG_PATH"
+
+        if git diff --quiet -- "$CHANGELOG_PATH"; then
+          echo "::notice::changelog unchanged."
+          exit 0
+        fi
+
+        git add -- "$CHANGELOG_PATH"
+        git commit --quiet -m "docs(changelog): record #${ISSUE_NUMBER}"
+
+        # The default branch may have moved while this ran. Rebase and retry rather than fail:
+        # only this action writes the file, so a rebase here cannot produce a content conflict.
+        for attempt in 1 2 3; do
+          if git push --quiet origin "$DEFAULT_BRANCH"; then
+            echo "Recorded #${ISSUE_NUMBER} at ${short_sha} in the changelog."
+            exit 0
+          fi
+          echo "::notice::push rejected, rebasing (attempt ${attempt})"
+          git fetch --quiet origin "$DEFAULT_BRANCH"
+          git rebase --quiet "origin/$DEFAULT_BRANCH" || { git rebase --abort || true; break; }
+        done
+
+        echo "::warning::Could not push the changelog entry for #${ISSUE_NUMBER}."

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

@@ -1,40 +1,40 @@
-# 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: 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