@plainconceptsplatform/workflows 0.1.0

package/loops/actions/cleanup-artifacts/action.yml

@@ -0,0 +1,64 @@
+name: Clean up artifacts
+description: Delete workflow artifacts older than the configured retention period.
+inputs:
+  token:
+    description: GitHub token with actions write access.
+    required: true
+  artifact-retention-days:
+    description: Retention period in days. Invalid or empty values use 3.
+    required: false
+    default: ''
+runs:
+  using: composite
+  steps:
+    - name: Delete expired artifacts
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        ARTIFACT_RETENTION_DAYS: ${{ inputs.artifact-retention-days }}
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          const parsedDays = Number.parseInt(process.env.ARTIFACT_RETENTION_DAYS, 10);
+          const days = Number.isInteger(parsedDays) && parsedDays > 0 ? parsedDays : 3;
+          const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+
+          core.info(`Retention: ${days} days (cutoff ${cutoff.toISOString()})`);
+
+          const artifacts = await github.paginate(github.rest.actions.listArtifactsForRepo, {
+            ...context.repo,
+            per_page: 100,
+          });
+
+          const expired = artifacts.filter((artifact) => new Date(artifact.created_at) < cutoff);
+
+          let deleted = 0;
+          const failed = [];
+
+          for (const artifact of expired) {
+            try {
+              await github.rest.actions.deleteArtifact({
+                ...context.repo,
+                artifact_id: artifact.id,
+              });
+
+              core.info(`Deleted ${artifact.name} (created ${artifact.created_at})`);
+              deleted += 1;
+            } catch (error) {
+              core.warning(`Could not delete ${artifact.name} (${artifact.id}): ${error.message}`);
+              failed.push(artifact.name);
+            }
+          }
+
+          await core.summary
+            .addHeading('Artifact cleanup', 2)
+            .addList([
+              `Retention: ${days} days (cutoff ${cutoff.toISOString()})`,
+              `Deleted: ${deleted}`,
+              `Failed to delete: ${failed.length}`,
+              `Within retention: ${artifacts.length - expired.length}`,
+            ])
+            .write();
+
+          if (failed.length > 0) {
+            core.setFailed(`${failed.length} artifact(s) could not be deleted: ${failed.join(', ')}`);
+          }

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

@@ -0,0 +1,42 @@
+name: Close agent issues
+description: Close every close_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
+runs:
+  using: composite
+  steps:
+    - name: Close issues
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        AGENT_OUTPUT_LIB: ${{ github.action_path }}/../agent-output.cjs
+        OUTPUT_FILE: ${{ inputs.output-file }}
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          const { readAgentItems } = require(process.env.AGENT_OUTPUT_LIB);
+          const items = readAgentItems(process.env.OUTPUT_FILE, 'close_issue');
+
+          let closed = 0;
+
+          for (const item of items) {
+            if (!item.item_number) {
+              core.warning(`close_issue item has no item_number, skipping: ${JSON.stringify(item)}`);
+              continue;
+            }
+
+            await github.rest.issues.update({
+              ...context.repo,
+              issue_number: Number(item.item_number),
+              state: 'closed',
+              state_reason: item.state_reason === 'not_planned' ? 'not_planned' : 'completed',
+            });
+
+            closed += 1;
+          }
+
+          core.info(`Closed ${closed} issue(s).`);

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

@@ -0,0 +1,51 @@
+name: Create agent issues
+description: Create every create_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
+outputs:
+  created-count:
+    description: Number of issues created.
+    value: ${{ steps.create.outputs.created-count }}
+  first-issue-number:
+    description: Issue number of the first issue created, or empty.
+    value: ${{ steps.create.outputs.first-issue-number }}
+runs:
+  using: composite
+  steps:
+    - name: Create issues
+      id: create
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        AGENT_OUTPUT_LIB: ${{ github.action_path }}/../agent-output.cjs
+        OUTPUT_FILE: ${{ inputs.output-file }}
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          const { readAgentItems } = require(process.env.AGENT_OUTPUT_LIB);
+          const items = readAgentItems(process.env.OUTPUT_FILE, 'create_issue');
+
+          const created = [];
+
+          for (const item of items) {
+            if (!item.title) {
+              core.warning(`create_issue item has no title, skipping: ${JSON.stringify(item)}`);
+              continue;
+            }
+
+            const { data } = await github.rest.issues.create({
+              ...context.repo,
+              title: item.title,
+              body: item.body ?? '',
+            });
+
+            created.push(data.number);
+            core.info(`Created #${data.number}: ${item.title}`);
+          }
+
+          core.setOutput('created-count', String(created.length));
+          core.setOutput('first-issue-number', created.length > 0 ? String(created[0]) : '');

package/loops/actions/create-issue-comment/action.yml

@@ -0,0 +1,28 @@
+name: Create issue comment
+description: Create a comment on 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
+  body:
+    description: Complete Markdown comment body.
+    required: true
+runs:
+  using: composite
+  steps:
+    - name: Create comment
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        ISSUE_NUMBER: ${{ inputs.issue-number }}
+        BODY: ${{ inputs.body }}
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          await github.rest.issues.createComment({
+            ...context.repo,
+            issue_number: Number(process.env.ISSUE_NUMBER),
+            body: process.env.BODY,
+          });

package/loops/actions/download-agent-output/action.yml

@@ -0,0 +1,52 @@
+name: Download agent output
+description: Download the agent artifact and expose the output JSON and bundle paths.
+inputs:
+  artifact-name:
+    description: >-
+      Artifact name to download. gh-aw prefixes it with the value it derives from the
+      workflow's inputs, so a workflow_call worker must pass the activation job's
+      artifact_prefix output followed by "agent", not the bare name.
+    required: true
+outputs:
+  output-file:
+    description: Path to agent_output.json, or empty if not found.
+    value: ${{ steps.download.outputs.output-file }}
+  bundle-file:
+    description: Path to the git bundle, or empty if not found.
+    value: ${{ steps.download.outputs.bundle-file }}
+  item-count:
+    description: Number of items in the agent output.
+    value: ${{ steps.download.outputs.item-count }}
+runs:
+  using: composite
+  steps:
+    - name: Download agent artifact
+      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+      with:
+        name: ${{ inputs.artifact-name }}
+        path: agent-artifact
+    - name: Locate output and bundle
+      id: download
+      shell: bash
+      env:
+        ARTIFACT_NAME: ${{ inputs.artifact-name }}
+      run: |
+        set -euo pipefail
+        OUTPUT_FILE=""
+        BUNDLE_FILE=""
+        ITEM_COUNT="0"
+
+        if [ -f "agent-artifact/agent_output.json" ]; then
+          OUTPUT_FILE="agent-artifact/agent_output.json"
+          ITEM_COUNT=$(jq '.items | length' "$OUTPUT_FILE")
+          BUNDLE_FILE=$(ls agent-artifact/aw-*.bundle 2>/dev/null | head -1 || true)
+        else
+          echo "::error::Artifact '$ARTIFACT_NAME' contained no agent_output.json. Nothing the agent proposed will be applied."
+          exit 1
+        fi
+
+        echo "Artifact '$ARTIFACT_NAME' carries $ITEM_COUNT item(s)."
+
+        echo "output-file=$OUTPUT_FILE" >> "$GITHUB_OUTPUT"
+        echo "bundle-file=$BUNDLE_FILE" >> "$GITHUB_OUTPUT"
+        echo "item-count=$ITEM_COUNT" >> "$GITHUB_OUTPUT"

package/loops/actions/identify-gate-subject/action.yml

@@ -0,0 +1,96 @@
+name: Identify gate subject
+description: Confirm the pull request is one we authored, resolve the issue it closes, and check that issue carries the required label.
+inputs:
+  token:
+    description: GitHub token with issues and pull-requests read access.
+    required: true
+  pr-number:
+    description: Pull request number to gate.
+    required: true
+  ci-conclusion:
+    description: Conclusion reported by the CI run that triggered this gate.
+    required: true
+  linked-issue:
+    description: Issue the pull request closes, when the router already resolved it.
+    required: false
+    default: ''
+  require-label:
+    description: Label the closing issue must carry. Empty disables the check.
+    required: false
+    default: ''
+outputs:
+  found:
+    description: Whether a valid gate subject was found.
+    value: ${{ steps.identify.outputs.found }}
+  pr:
+    description: Pull request number.
+    value: ${{ steps.identify.outputs.pr }}
+  issue:
+    description: Issue number the pull request closes.
+    value: ${{ steps.identify.outputs.issue }}
+  conclusion:
+    description: CI conclusion, passed through unchanged.
+    value: ${{ steps.identify.outputs.conclusion }}
+runs:
+  using: composite
+  steps:
+    - name: Identify pull request and closing issue
+      id: identify
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        REPO: ${{ github.repository }}
+        PR_NUMBER: ${{ inputs.pr-number }}
+        CONCLUSION: ${{ inputs.ci-conclusion }}
+        LINKED_ISSUE: ${{ inputs.linked-issue }}
+        REQUIRE_LABEL: ${{ inputs.require-label }}
+      run: |
+        set -euo pipefail
+
+        none() {
+          echo "found=false" >> "$GITHUB_OUTPUT"
+          echo "$1"
+          exit 0
+        }
+
+        pr="$(gh pr view "$PR_NUMBER" --repo "$REPO" \
+          --json state,author,closingIssuesReferences,body)"
+
+        [ "$(jq -r '.state' <<<"$pr")" = "OPEN" ] || none "PR #$PR_NUMBER is not open"
+
+        # Use GitHub's bot flag because App login formats differ across APIs.
+        if [ "$(jq -r '.author.is_bot' <<<"$pr")" != "true" ]; then
+          none "PR #$PR_NUMBER was authored by $(jq -r '.author.login' <<<"$pr"), a human."
+        fi
+
+        issue="$LINKED_ISSUE"
+
+        if [ -z "$issue" ]; then
+          issue="$(jq -r '.closingIssuesReferences[0].number // empty' <<<"$pr")"
+        fi
+
+        if [ -z "$issue" ]; then
+          issue="$(jq -r '.body // ""' <<<"$pr" |
+            grep -oiE '(close[sd]?|fixe?[sd]?|resolve[sd]?) +#[0-9]+' |
+            grep -oE '[0-9]+' | head -n 1 || true)"
+        fi
+
+        [ -n "$issue" ] || none "PR #$PR_NUMBER does not close a numbered issue"
+
+        if [ -n "$REQUIRE_LABEL" ]; then
+          labels="$(gh issue view "$issue" --repo "$REPO" --json labels \
+            --jq '[.labels[].name]')"
+
+          if ! jq -e --arg name "$REQUIRE_LABEL" 'index($name)' >/dev/null <<<"$labels"; then
+            none "issue #$issue does not carry $REQUIRE_LABEL (has: $(jq -r 'join(", ")' <<<"$labels"))"
+          fi
+        fi
+
+        {
+          echo "found=true"
+          echo "pr=$PR_NUMBER"
+          echo "issue=$issue"
+          echo "conclusion=$CONCLUSION"
+        } >> "$GITHUB_OUTPUT"
+
+        echo "PR #$PR_NUMBER closes #$issue; CI concluded $CONCLUSION"

package/loops/actions/link-pr-to-issue/action.yml

@@ -0,0 +1,39 @@
+name: Link pull request to issue
+description: Ensure the pull request body carries a closing reference to its source issue.
+inputs:
+  token:
+    description: GitHub token with pull-requests write access.
+    required: true
+  pr-number:
+    description: Pull request number.
+    required: true
+  issue-number:
+    description: Issue number the pull request should close.
+    required: true
+runs:
+  using: composite
+  steps:
+    - name: Ensure a closing reference
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        REPO: ${{ github.repository }}
+        PR_NUMBER: ${{ inputs.pr-number }}
+        ISSUE_NUMBER: ${{ inputs.issue-number }}
+      run: |
+        set -euo pipefail
+
+        pr="$(gh pr view "$PR_NUMBER" --repo "$REPO" --json closingIssuesReferences,body)"
+
+        if [ "$(jq '.closingIssuesReferences | length' <<<"$pr")" -gt 0 ]; then
+          echo "PR #$PR_NUMBER already closes an issue."
+          exit 0
+        fi
+
+        # A closing reference can only be created from the pull request body; there is no
+        # REST or GraphQL mutation for it.
+        body="$(jq -r '.body // ""' <<<"$pr")"
+        printf '%s\n\nCloses #%s\n' "$body" "$ISSUE_NUMBER" > /tmp/pr-body.md
+
+        gh pr edit "$PR_NUMBER" --repo "$REPO" --body-file /tmp/pr-body.md
+        echo "Added 'Closes #$ISSUE_NUMBER' to PR #$PR_NUMBER."

package/loops/actions/list-open-issues/action.yml

@@ -0,0 +1,32 @@
+name: List open issues
+description: |
+  Writes all open issues (number, title, labels) to `/tmp/gh-aw/agent/open-issues.json`
+  so the agent can check for semantic duplicates without spending turns discovering them.
+inputs:
+  token:
+    description: GitHub token with issues:read permission.
+    required: true
+  repo:
+    description: Repository in `owner/name` format.
+    required: true
+  output-path:
+    description: Path to write the JSON output.
+    required: false
+    default: /tmp/gh-aw/agent/open-issues.json
+runs:
+  using: composite
+  steps:
+    - name: List open issues
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        REPO: ${{ inputs.repo }}
+        OUTPUT_PATH: ${{ inputs.output-path }}
+      run: |
+        set -euo pipefail
+        mkdir -p "$(dirname "$OUTPUT_PATH")"
+        gh issue list --repo "$REPO" --state open --limit 500 \
+          --json number,title,labels \
+          --jq '[.[] | {number, title, labels: [.labels[].name]}]' \
+          > "$OUTPUT_PATH"
+        echo "Wrote $(jq 'length' "$OUTPUT_PATH") open issues to $OUTPUT_PATH"

package/loops/actions/load-issue-context/action.yml

@@ -0,0 +1,42 @@
+name: Load issue context
+description: Write issue metadata and comment context to a JSON file.
+inputs:
+  token:
+    description: GitHub token used by github-script.
+    required: true
+  issue-number:
+    description: Issue number to load.
+    required: true
+  output-path:
+    description: Absolute path where context JSON is written.
+    required: true
+runs:
+  using: composite
+  steps:
+    - name: Load issue and comments
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        ISSUE_NUMBER: ${{ inputs.issue-number }}
+        OUTPUT_PATH: ${{ inputs.output-path }}
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          const fs = require('fs');
+          const issueNumber = Number(process.env.ISSUE_NUMBER);
+          const issue = await github.rest.issues.get({ ...context.repo, issue_number: issueNumber });
+          const comments = await github.paginate(github.rest.issues.listComments, {
+            ...context.repo, issue_number: issueNumber, per_page: 100,
+          });
+
+          fs.mkdirSync(require('path').dirname(process.env.OUTPUT_PATH), { recursive: true });
+          fs.writeFileSync(process.env.OUTPUT_PATH, JSON.stringify({
+            number: issue.data.number,
+            title: issue.data.title,
+            body: issue.data.body,
+            labels: issue.data.labels.map(({ name }) => name),
+            comments: comments.map(({ user, author_association, body }) => ({
+              author: user.login,
+              association: author_association,
+              body,
+            })),
+          }, null, 2));

package/loops/actions/merge-agent-pr/action.yml

@@ -0,0 +1,35 @@
+name: Merge agent pull request
+description: Read merge_pull_request from agent_output.json and merge the PR via gh.
+inputs:
+  output-file:
+    description: Path to agent_output.json.
+    required: true
+  token:
+    description: GitHub token with pull-requests:write and contents:write.
+    required: true
+  repo:
+    description: Target repository in owner/name format.
+    required: false
+    default: ${{ github.repository }}
+runs:
+  using: composite
+  steps:
+    - name: Merge pull request
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        OUTPUT_FILE: ${{ inputs.output-file }}
+        REPO: ${{ inputs.repo }}
+      run: |
+        set -euo pipefail
+        [ -f "$OUTPUT_FILE" ] || exit 0
+
+        jq -c '.items[] | select(.type == "merge_pull_request")' "$OUTPUT_FILE" | while read -r item; do
+          PR_NUM=$(echo "$item" | jq -er '.pr_number // .item_number // empty')
+          [[ "$PR_NUM" =~ ^[1-9][0-9]*$ ]] || { echo "::error::Invalid pull request number: $PR_NUM"; exit 1; }
+
+          HEAD_SHA=$(gh pr view "$PR_NUM" --repo "$REPO" --json headRefOid --jq '.headRefOid')
+          [[ "$HEAD_SHA" =~ ^[0-9a-fA-F]{40}$ ]] || { echo "::error::Invalid pull request head SHA for #$PR_NUM"; exit 1; }
+
+          gh pr merge "$PR_NUM" --repo "$REPO" --squash --match-head-commit "$HEAD_SHA"
+        done

package/loops/actions/push-agent-branch/action.yml

@@ -0,0 +1,44 @@
+name: Push agent branch
+description: Read push_to_pull_request_branch from agent_output.json and fast-forward from its git bundle.
+inputs:
+  output-file:
+    description: Path to agent_output.json.
+    required: true
+  bundle-file:
+    description: Path to the git bundle from the agent artifact.
+    required: false
+    default: ''
+  token:
+    description: GitHub token with contents:write.
+    required: true
+runs:
+  using: composite
+  steps:
+    - name: Configure git credentials
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+      run: |
+        git config --global url."https://x-access-token:${GH_TOKEN}@github.com/".insteadOf "https://github.com/"
+    - name: Read pull request branch
+      id: request
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        OUTPUT_FILE: ${{ inputs.output-file }}
+        BUNDLE_FILE: ${{ inputs.bundle-file }}
+      run: |
+        set -euo pipefail
+        [ -f "$OUTPUT_FILE" ] || exit 0
+
+        ITEM=$(jq -c '.items[] | select(.type == "push_to_pull_request_branch")' "$OUTPUT_FILE")
+        [ -n "$ITEM" ] || exit 0
+
+        BRANCH=$(echo "$ITEM" | jq -r '.branch')
+        echo "branch=$BRANCH" >> "$GITHUB_OUTPUT"
+    - name: Apply bundle to pull request branch
+      if: steps.request.outputs.branch != '' && inputs.bundle-file != ''
+      uses: ./.github/actions/apply-agent-bundle
+      with:
+        bundle-file: ${{ inputs.bundle-file }}
+        target-branch: ${{ steps.request.outputs.branch }}

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

@@ -0,0 +1,34 @@
+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: Newline-delimited labels to remove.
+    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: |
+          for (const label of process.env.LABELS.split(/\r?\n/).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;
+            }
+          }