@plainconceptsplatform/workflows 0.1.0

package/loops/actions/stale-recovery/action.yml

@@ -0,0 +1,287 @@
+name: Recover stale agent work
+description: Reconcile Refine, Implement, and Merge Gate claims whose bot-working label has outlived the staleness threshold, and dispatch merge-gate for bot PRs with failed CI.
+inputs:
+  token:
+    description: GitHub token with issues write and pull-requests read access.
+    required: true
+  stale-threshold-hours:
+    description: Hours after which a bot-working claim is stale. Invalid or empty values use 2.
+    required: false
+    default: ''
+  refine-marker:
+    description: Marker identifying the comment a Refine run posts when it asks the author a question.
+    required: false
+    default: '<!-- agent-refine -->'
+  working-label:
+    description: Label marking an issue the bot currently owns.
+    required: false
+    default: bot-working
+  refine-label:
+    description: Label marking an issue queued for refinement.
+    required: false
+    default: refine
+  direct-label:
+    description: Label marking an issue with a free-form direct instruction.
+    required: false
+    default: direct
+  implement-label:
+    description: Label marking an issue queued for implementation.
+    required: false
+    default: implement
+  review-label:
+    description: Label marking an issue that needs a human.
+    required: false
+    default: review
+  ci-workflow-name:
+    description: Name of the CI workflow whose failure should trigger a merge-gate dispatch.
+    required: false
+    default: 'App: CI'
+  router-workflow-name:
+    description: Name of the work router workflow to dispatch.
+    required: false
+    default: 'All Work Router'
+runs:
+  using: composite
+  steps:
+    - name: Reconcile stale claims
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        STALE_THRESHOLD_HOURS: ${{ inputs.stale-threshold-hours }}
+        REFINE_MARKER: ${{ inputs.refine-marker }}
+        WORKING_LABEL: ${{ inputs.working-label }}
+        REFINE_LABEL: ${{ inputs.refine-label }}
+        DIRECT_LABEL: ${{ inputs.direct-label }}
+        IMPLEMENT_LABEL: ${{ inputs.implement-label }}
+        REVIEW_LABEL: ${{ inputs.review-label }}
+        CI_WORKFLOW_NAME: ${{ inputs.ci-workflow-name }}
+        ROUTER_WORKFLOW_NAME: ${{ inputs.router-workflow-name }}
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          const WORKING = process.env.WORKING_LABEL;
+          const REVIEW = process.env.REVIEW_LABEL;
+          const MARKER = process.env.REFINE_MARKER;
+          const CI_WORKFLOW_NAME = process.env.CI_WORKFLOW_NAME;
+          const ROUTER_WORKFLOW_NAME = process.env.ROUTER_WORKFLOW_NAME;
+
+          const parsedHours = Number.parseInt(process.env.STALE_THRESHOLD_HOURS, 10);
+          const hours = Number.isInteger(parsedHours) && parsedHours > 0 ? parsedHours : 2;
+          const cutoff = new Date(Date.now() - hours * 60 * 60 * 1000);
+
+          core.info(`Stale threshold: ${hours}h (cutoff ${cutoff.toISOString()})`);
+
+          const staleIssuesLabelled = async (label) => {
+            const issues = await github.paginate(github.rest.issues.listForRepo, {
+              ...context.repo,
+              state: 'open',
+              labels: `${WORKING},${label}`,
+              per_page: 100,
+            });
+
+            return issues.filter((issue) => new Date(issue.updated_at) < cutoff);
+          };
+
+          const removeWorking = async (issueNumber) => {
+            try {
+              await github.rest.issues.removeLabel({
+                ...context.repo,
+                issue_number: issueNumber,
+                name: WORKING,
+              });
+            } catch (error) {
+              if (error.status !== 404) throw error;
+            }
+          };
+
+          // Open bot pull requests keep work in flight. GraphQL exposes authorship and closing
+          // references together, so use `__typename` instead of matching a login.
+          const openPullRequests = [];
+
+          for (let cursor = null; ; ) {
+            const page = await github.graphql(
+              `query($owner: String!, $name: String!, $cursor: String) {
+                repository(owner: $owner, name: $name) {
+                  pullRequests(states: OPEN, first: 100, after: $cursor) {
+                    pageInfo { hasNextPage endCursor }
+                    nodes {
+                      number
+                      updatedAt
+                      author { __typename }
+                      closingIssuesReferences(first: 10) {
+                        nodes { number labels(first: 20) { nodes { name } } }
+                      }
+                    }
+                  }
+                }
+              }`,
+              { owner: context.repo.owner, name: context.repo.repo, cursor },
+            );
+
+            const { nodes, pageInfo } = page.repository.pullRequests;
+            openPullRequests.push(...nodes);
+
+            if (!pageInfo.hasNextPage) break;
+            cursor = pageInfo.endCursor;
+          }
+
+          const botPullRequests = openPullRequests.filter(
+            (pr) => pr.author?.__typename === 'Bot',
+          );
+
+          const issuesWithOpenBotPr = new Set(
+            botPullRequests.flatMap((pr) => pr.closingIssuesReferences.nodes.map((n) => n.number)),
+          );
+
+          const summary = {
+            refineEscalated: 0,
+            refineAwaitingAuthor: 0,
+            implementReleased: 0,
+            directReleased: 0,
+            mergeGateReleased: 0,
+            mergeGateDispatched: 0,
+          };
+
+          for (const issue of await staleIssuesLabelled(process.env.REFINE_LABEL)) {
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              ...context.repo,
+              issue_number: issue.number,
+              per_page: 100,
+            });
+
+            const lastMarker = comments.filter((c) => (c.body ?? '').includes(MARKER)).pop();
+            const lastHuman = comments.filter((c) => c.user?.type !== 'Bot').pop();
+
+            // The bot asked a question nobody has answered yet. Escalating would drop the
+            // question on the floor, so leave the claim in place.
+            if (lastMarker && !(lastHuman && new Date(lastHuman.created_at) > new Date(lastMarker.created_at))) {
+              core.info(`#${issue.number}: awaiting author reply, left alone`);
+              summary.refineAwaitingAuthor += 1;
+              continue;
+            }
+
+            await removeWorking(issue.number);
+            await github.rest.issues.addLabels({
+              ...context.repo,
+              issue_number: issue.number,
+              labels: [REVIEW],
+            });
+
+            core.info(`#${issue.number}: escalated to ${REVIEW}`);
+            summary.refineEscalated += 1;
+          }
+
+          for (const issue of await staleIssuesLabelled(process.env.IMPLEMENT_LABEL)) {
+            if (issuesWithOpenBotPr.has(issue.number)) {
+              core.info(`#${issue.number}: open bot pull request still in flight, left alone`);
+              continue;
+            }
+
+            await removeWorking(issue.number);
+            core.info(`#${issue.number}: released`);
+            summary.implementReleased += 1;
+          }
+
+          for (const issue of await staleIssuesLabelled(process.env.DIRECT_LABEL)) {
+            if (issuesWithOpenBotPr.has(issue.number)) {
+              core.info(`#${issue.number}: open bot pull request still in flight, left alone`);
+              continue;
+            }
+
+            await removeWorking(issue.number);
+            await github.rest.issues.addLabels({
+              ...context.repo,
+              issue_number: issue.number,
+              labels: [REVIEW],
+            });
+            core.info(`#${issue.number}: direct released, escalated to ${REVIEW}`);
+            summary.directReleased += 1;
+          }
+
+          for (const pr of botPullRequests.filter((p) => new Date(p.updatedAt) < cutoff)) {
+            for (const issue of pr.closingIssuesReferences.nodes) {
+              if (!issue.labels.nodes.some((label) => label.name === WORKING)) {
+                continue;
+              }
+
+              await removeWorking(issue.number);
+              core.info(`PR #${pr.number} / issue #${issue.number}: released`);
+              summary.mergeGateReleased += 1;
+            }
+          }
+
+          // The workflow_run trigger does not fire for PR-triggered CI completions on
+          // feature branches. This polls every stale-recovery cycle (2h) for bot PRs
+          // whose CI concluded failure and dispatches the merge-gate, which is the same
+          // thing the workflow_run trigger would have done. A run already in progress
+          // for the same PR is skipped by the router's concurrency group.
+          const ciWorkflow = await github.rest.actions.getRepoWorkflow({
+            ...context.repo,
+            workflow_id: CI_WORKFLOW_NAME,
+          }).catch(() => null);
+
+          if (ciWorkflow) {
+            for (const pr of botPullRequests) {
+              const runs = await github.rest.actions.listWorkflowRuns({
+                ...context.repo,
+                workflow_id: CI_WORKFLOW_NAME,
+                branch: pr.number.toString(),
+                status: 'completed',
+                per_page: 1,
+              }).catch(() => ({ data: { workflow_runs: [] } }));
+
+              const latestRun = runs.data.workflow_runs[0];
+              if (!latestRun || latestRun.conclusion !== 'failure') continue;
+
+              // Skip if the issue already carries review (the agent already gave up).
+              const issueNumbers = pr.closingIssuesReferences.nodes.map((n) => n.number);
+              const hasReview = await Promise.all(
+                issueNumbers.map(async (n) => {
+                  const labels = await github.rest.issues.listLabelsOnIssue({
+                    ...context.repo,
+                    issue_number: n,
+                  }).catch(() => ({ data: [] }));
+                  return labels.data.some((l) => l.name === REVIEW);
+                }),
+              );
+              if (hasReview.some(Boolean)) continue;
+
+              const routerWorkflow = await github.rest.actions.getRepoWorkflow({
+                ...context.repo,
+                workflow_id: ROUTER_WORKFLOW_NAME,
+              }).catch(() => null);
+
+              if (routerWorkflow) {
+                // Resolve the linked issue number for the dispatch.
+                const linkedIssue = issueNumbers[0];
+                if (!linkedIssue) continue;
+
+                await github.rest.actions.createWorkflowDispatch({
+                  ...context.repo,
+                  workflow_id: ROUTER_WORKFLOW_NAME,
+                  ref: 'main',
+                  inputs: {
+                    operation: 'merge-gate',
+                    'pr-number': pr.number.toString(),
+                    'ci-conclusion': 'failure',
+                    'ci-run-id': latestRun.id.toString(),
+                  },
+                });
+
+                core.info(`PR #${pr.number}: dispatched merge-gate for failed CI (run ${latestRun.id})`);
+                summary.mergeGateDispatched += 1;
+              }
+            }
+          }
+
+          await core.summary
+            .addHeading('Stale recovery', 2)
+            .addList([
+              `Threshold: ${hours} hours (cutoff ${cutoff.toISOString()})`,
+              `Refine escalated to ${REVIEW}: ${summary.refineEscalated}`,
+              `Refine awaiting author: ${summary.refineAwaitingAuthor}`,
+              `Implement released: ${summary.implementReleased}`,
+              `Direct released: ${summary.directReleased}`,
+              `Merge Gate released: ${summary.mergeGateReleased}`,
+              `Merge Gate dispatched for failed CI: ${summary.mergeGateDispatched}`,
+            ])
+            .write();

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

@@ -0,0 +1,57 @@
+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-refine-output/action.yml

@@ -0,0 +1,43 @@
+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

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

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Print the deterministic Refine outcome: complete, questions, or invalid.
+
+set -euo pipefail
+
+output_file="$1"
+marker="$2"
+comment_prefix="$3"
+issue_number="$4"
+
+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" '
+  def has_replacement_body:
+    any(.items[]; .type == "update_issue" and
+      (.item_number == null or (.item_number | tostring) == $issue) and
+      (.body | type == "string") and (.body | test("[^[:space:]]")));
+
+  def has_update:
+    any(.items[]; .type == "update_issue");
+
+  def has_only_source_items:
+    all(.items[];
+      (
+        .type == "update_issue" and
+        (.item_number == null or (.item_number | tostring) == $issue)
+      ) or
+      (
+        .type == "add_comment" and
+        (.item_number | tostring) == $issue
+      ));
+
+  def has_clarification:
+    any(.items[]; .type == "add_comment" and (.item_number | tostring) == $issue and
+      (.body | type == "string") and
+      (.body | split($marker) | join("") | split($prefix) | join("") |
+        gsub("<[^>]*>"; "") | test("[[:alnum:]]")));
+
+  if has_replacement_body and has_only_source_items then "complete"
+  elif has_clarification and (has_update | not) and has_only_source_items then "questions"
+  else "invalid"
+  end
+' "$output_file"

package/loops/actions/verify-composite-actions/action.yml

@@ -0,0 +1,8 @@
+name: Verify composite actions
+description: Check every local composite action manifest parses and uses only contexts a composite action actually has.
+runs:
+  using: composite
+  steps:
+    - name: Validate composite action manifests
+      shell: bash
+      run: bash "${GITHUB_ACTION_PATH}/verify-composite-actions.sh"

package/loops/actions/verify-composite-actions/verify-composite-actions.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Validate every local composite action manifest.
+#
+# The runner evaluates ${{ }} everywhere in an action.yml, including inside `description:`,
+# and a composite action has no `needs`, `jobs` or `secrets` context. Referencing one, even as
+# documentation, fails the action at load time with "Unrecognized named-value", which surfaces
+# as a one-second job failure with no other clue.
+#
+# `gh aw compile` does not read these files and actionlint does not lint them, so this is the
+# only thing between a typo here and a runtime failure.
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ACTIONS_DIR="${1:-$(cd "${HERE}/.." && pwd)}"
+
+PASS=0
+FAIL=0
+
+while IFS= read -r manifest; do
+  rel="${manifest#"${ACTIONS_DIR}/"}"
+
+  if ! python3 -c "import sys, yaml; yaml.safe_load(open(sys.argv[1], encoding='utf-8'))" "$manifest" 2>/dev/null; then
+    FAIL=$((FAIL + 1))
+    echo "FAIL: ${rel} is not valid YAML" >&2
+    continue
+  fi
+
+  # Only what is inside an expression matters; the same word in prose is fine.
+  offenders="$(grep -oE '\$\{\{[^}]*\}\}' "$manifest" |
+    grep -E '\b(needs|jobs|secrets)\.' || true)"
+
+  if [ -n "$offenders" ]; then
+    FAIL=$((FAIL + 1))
+    echo "FAIL: ${rel} uses a context a composite action does not have:" >&2
+    printf '  %s\n' "$offenders" >&2
+    continue
+  fi
+
+  PASS=$((PASS + 1))
+done < <(find "$ACTIONS_DIR" -name 'action.yml' | sort)
+
+echo
+if [ "$FAIL" -eq 0 ]; then
+  echo "Composite action manifests: ${PASS} valid"
+else
+  echo "Composite action manifests: ${PASS} valid, ${FAIL} INVALID" >&2
+fi
+
+exit $((FAIL > 0))

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

@@ -0,0 +1,8 @@
+name: Verify refine output validation
+description: Exercise deterministic Refine output validation regressions.
+runs:
+  using: composite
+  steps:
+    - name: Verify refinement outcomes
+      shell: bash
+      run: bash "${{ github.action_path }}/verify-refine-output.sh"

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

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Exercise real validation script so incomplete agent output cannot be applied.
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VALIDATOR="${HERE}/../validate-refine-output/validate-refine-output.sh"
+MARKER='<!-- agent-refine -->'
+PREFIX='Refinement update'
+TEMP_DIR="$(mktemp -d)"
+
+trap 'rm -rf "$TEMP_DIR"' EXIT
+
+PASS=0
+FAIL=0
+
+assert_output() {
+  local label="$1"
+  local expected="$2"
+  local payload="$3"
+  local output_file="${TEMP_DIR}/agent_output.json"
+  local actual
+
+  printf '%s' "$payload" > "$output_file"
+  actual="$(bash "$VALIDATOR" "$output_file" "$MARKER" "$PREFIX" 42)"
+
+  if [ "$actual" = "$expected" ]; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    printf 'FAIL: %s\n  expected: %s\n  actual:   %s\n' "$label" "$expected" "$actual" >&2
+  fi
+}
+
+assert_output 'complete refinement is classified without labels' complete \
+  '{"items":[{"type":"update_issue","item_number":42,"body":"# User story"}]}'
+assert_output 'fallback-targeted refinement is complete' complete \
+  '{"items":[{"type":"update_issue","body":"# User story"}]}'
+assert_output 'clarification is classified without labels' questions \
+  '{"items":[{"type":"add_comment","item_number":42,"body":"<!-- agent-refine -->\nRefinement update\nWhich users need this feature?"}]}'
+assert_output 'agent label actions are invalid' invalid \
+  '{"items":[{"type":"update_issue","item_number":42,"body":"# User story"},{"type":"add_labels","item_number":42,"labels":[{"name":"review"}]}]}'
+assert_output 'single hyphen comment is invalid' invalid \
+  '{"items":[{"type":"add_comment","body":"-"}]}'
+assert_output 'marker and prefix alone are invalid' invalid \
+  '{"items":[{"type":"add_comment","body":"<!-- agent-refine -->\nRefinement update\n---"}]}'
+assert_output 'blank issue body is invalid' invalid \
+  '{"items":[{"type":"update_issue","item_number":42,"body":" \n\t "}]}'
+assert_output 'question with an update is complete' complete \
+  '{"items":[{"type":"update_issue","item_number":42,"body":"# User story"},{"type":"add_comment","item_number":42,"body":"Which users need this feature?"}]}'
+assert_output 'question with a blank update is invalid' invalid \
+  '{"items":[{"type":"update_issue","item_number":42,"body":" "},{"type":"add_comment","item_number":42,"body":"Which users need this feature?"}]}'
+assert_output 'wrong issue output is invalid' invalid \
+  '{"items":[{"type":"add_comment","item_number":7,"body":"Which users need this feature?"}]}'
+assert_output 'complete output cannot update another issue' invalid \
+  '{"items":[{"type":"update_issue","item_number":42,"body":"# User story"},{"type":"update_issue","item_number":7,"body":"# Other story"}]}'
+
+echo
+if [ "$FAIL" -eq 0 ]; then
+  echo "Refine output validation: ${PASS} passed"
+else
+  echo "Refine output validation: ${PASS} passed, ${FAIL} FAILED" >&2
+fi
+
+exit $((FAIL > 0))

package/loops/actions/verify-route-matrix/action.yml

@@ -0,0 +1,8 @@
+name: Verify route matrix
+description: Exercise the router's classifier against every supported event, and check that each route and dispatch operation has a job in work-router.yml.
+runs:
+  using: composite
+  steps:
+    - name: Run route matrix verification
+      shell: bash
+      run: bash "${GITHUB_ACTION_PATH}/verify-route-matrix.sh"