@plainconceptsplatform/workflows 1.19.0 → 1.20.0

package/dist/workflow-catalog.js

@@ -16,7 +16,7 @@ export const workflowRoutes = [
     { name: "merge-gate", worker: "agent-merge-gate.md", description: "Decides what happens to the pull request the merge train hands it, the bot's or a person's: repair it, merge it, or hand it to a human.", defaultEnabled: true },
     { name: "audit", worker: "agent-audit.md", description: "Read-only repository audit. Finds 5-7 problems, scores each 1-10, and files a tracking report plus one story issue per top finding, each sized for Refine.", defaultEnabled: true },
     { name: "docs-audit", worker: "agent-docs-audit.md", description: "Read-only documentation audit, every fortnight. Checks the documentation against the code and the Platform standard, and files one issue that Refine then sizes and splits, only when something is stale.", defaultEnabled: false },
-    { name: "release", worker: "agent-release.md", description: "Writes release notes from the commit log, then a deterministic job opens a version-bump pull request with auto-merge; once it merges, release-tag.yml tags the commit and publishes the GitHub Release. Manual dispatch only (operation=release).", defaultEnabled: true, companions: ["release-tag.yml"] },
+    { name: "release", worker: "agent-release.md", description: "Writes release notes from the commit log, then a deterministic job opens a version-bump pull request with auto-merge; once it merges, release-tag.yml tags the commit and publishes the GitHub Release. Manual dispatch only (operation=release), or release-to-production.yml, which also deploys the new tag to production.", defaultEnabled: true, companions: ["release-tag.yml", "release-to-production.yml"] },
 ];
 /** What an install with no explicit selection gets. An optional worker is added by name. */
 export const defaultRouteNames = workflowRoutes

package/loops/actions/verify-route-matrix/verify-route-matrix.sh

@@ -3356,7 +3356,7 @@ for job in authorize classify; do
   sed -n "/^  ${job}:\$/,/^    runs-on:/p" "${WORKFLOWS_DIR}/work-router.yml" | grep -qF "if: vars.AGENTIC_WORKFLOWS_DISABLED == ''" ||
     { OFF_OK=0; echo "FAIL: the router's ${job} job ignores AGENTIC_WORKFLOWS_DISABLED" >&2; }
 done
-for f in "${WORKFLOWS_DIR}/authorize-bot-work.yml" "${WORKFLOWS_DIR}/release-tag.yml"; do
+for f in "${WORKFLOWS_DIR}/authorize-bot-work.yml" "${WORKFLOWS_DIR}/release-tag.yml" "${WORKFLOWS_DIR}/release-to-production.yml"; do
   [ -f "$f" ] || continue
   grep -qF "vars.AGENTIC_WORKFLOWS_DISABLED == ''" "$f" ||
     { OFF_OK=0; echo "FAIL: $(basename "$f") ignores AGENTIC_WORKFLOWS_DISABLED" >&2; }
@@ -3670,6 +3670,30 @@ fi
   if [ "$GATE_RUN_ID_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
+echo "── Release to production ──────────────────────────────────────────────────"
+
+# One button ships a release: release-to-production.yml runs the release worker with deploy=true
+# (the router's workflow_dispatch is at GitHub's ten-input limit), the release pull request carries
+# a marker, and release-tag.yml deploys the tag only when it finds it. A release without the marker
+# must keep not deploying.
+RTP_YML="${WORKFLOWS_DIR}/release-to-production.yml"
+RT_YML="${WORKFLOWS_DIR}/release-tag.yml"
+if [ -f "$RTP_YML" ] && worker_installed release; then
+  RTP_OK=1
+  rtp() { grep -qE "$1" "$2" || { RTP_OK=0; echo "FAIL: release to production: $3" >&2; }; }
+  rtp 'uses: \./\.github/workflows/agent-release\.lock\.yml' "$RTP_YML" 'the button must run the release worker'
+  rtp '^      deploy: "true"$' "$RTP_YML" 'the button must ask the release worker for a deploy'
+  rtp 'default: minor' "$RTP_YML" 'the button must default to a minor bump'
+  rtp '^    permissions: write-all$' "$RTP_YML" 'the button must grant the worker write-all, or the run never starts'
+  if grep -qE '^      deploy:' "$ROUTER_YML"; then RTP_OK=0; echo "FAIL: release to production: the router's workflow_dispatch is at the ten-input limit; deploy belongs to the button" >&2; fi
+  rtp '<!-- release-deploy -->' "${WORKFLOWS_DIR}/agent-release.md" 'the release worker never writes the deploy marker'
+  rtp 'if \[ "\$DEPLOY" = "true" \]' "${WORKFLOWS_DIR}/agent-release.md" 'the deploy marker must depend on the deploy input'
+  rtp "if: steps.release.outputs.deploy == 'true'" "$RT_YML" 'release-tag.yml must deploy only when the release asked for it'
+  rtp 'gh workflow run "\$DEPLOY_WORKFLOW" --repo "\$REPO" --ref "\$TAG"' "$RT_YML" 'release-tag.yml must start the deploy on the tag'
+  rtp '^  DEPLOY_WORKFLOW: ' "$RT_YML" 'release-tag.yml does not declare DEPLOY_WORKFLOW'
+  if [ "$RTP_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+fi
+
 echo "── App error privacy ─────────────────────────────────────────────────────"
 
 # The application error report files into the private repository rather than out of it, so

package/loops/docs/diagrams.md

@@ -599,6 +599,7 @@ nothing reaches `main` except through a pull request.
 ```mermaid
 flowchart TD
     relStart("Work Router<br/>release route<br/>operation=release") --> relFacts
+    relButton("Release to production button<br/>bump (default minor), deploy=true") --> relFacts
     relFacts("Facts (rung 3)<br/>Commit log since the last tag<br/>and the current version, to disk") --> relAgent
     relAgent("Agent (rung 5)<br/>Categorise by conventional-commit<br/>prefix, write release-notes.md.<br/>The only judgement in this route") --> relNoop
     relNoop("noop<br/>the agent writes a file,<br/>not a GitHub object") --> relConclude
@@ -607,7 +608,11 @@ flowchart TD
     relMerge{"CI green and<br/>auto-merge allowed?"}
     relMerge -->|yes| relTag
     relMerge -.->|auto-merge disabled| relOpen
-    relTag("release-tag.yml on push to main<br/>GITHUB_TOKEN: tag vX.Y.Z,<br/>Release with the PR body as notes") --> relDone
+    relTag("release-tag.yml on push to main<br/>GITHUB_TOKEN: tag vX.Y.Z,<br/>Release with the PR body as notes") --> relDeployQ
+    relDeployQ{"Deploy marker<br/>on the release PR?"}
+    relDeployQ -->|no| relDone
+    relDeployQ -->|yes| relDeploy
+    relDeploy(("Deploying<br/>DEPLOY_WORKFLOW started on the tag,<br/>pro reviewers still apply"))
     relConclude -.->|fails| relFail
     relOpen(("PR left open<br/>warning names the fix"))
     relDone(("Released<br/>tag and Release published,<br/>no tag-triggered workflow fired"))
@@ -620,16 +625,20 @@ flowchart TD
     classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class relStart start
-    class relFacts,relAgent,relNoop,relPr,relTag action
-    class relConclude,relMerge decision
+    class relButton,relFacts,relAgent,relNoop,relPr,relTag action
+    class relConclude,relMerge,relDeployQ decision
     class relFail failure
     class relOpen idle
-    class relDone success
+    class relDone,relDeploy success
 ```
 
 The version bump, the tag and the Release are deterministic on purpose. The agent's only output is
 a file on disk, so a confused model cannot publish a release. The tag and the Release use
 `GITHUB_TOKEN` so that a consumer deploying on `v*` tags does not deploy because a release was cut.
+The **Release to production** button (`release-to-production.yml`) is the one way a release deploys:
+it runs the worker directly with `deploy=true` (the router's dispatch is at GitHub's ten-input
+limit), the release pull request carries `<!-- release-deploy -->`,
+and only then does `release-tag.yml` start `DEPLOY_WORKFLOW` on the tag, explicitly.
 
 
 ---

package/loops/workflows/agent-release.md

@@ -40,6 +40,11 @@ on:
         required: false
         type: string
         default: "auto"
+      deploy:
+        description: "true when release-to-production.yml asked for a deploy: the release PR then carries the deploy marker"
+        required: false
+        type: string
+        default: "false"
 
 runs-on: agents-arc
 runs-on-slim: agents-arc
@@ -233,10 +238,18 @@ jobs:
           BASE: ${{ steps.branch.outputs.base }}
           BRANCH: ${{ steps.branch.outputs.branch }}
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          DEPLOY: ${{ inputs.deploy }}
         run: |
           set -euo pipefail
+          # The deploy marker is what makes release-tag.yml start the production deploy on the
+          # new tag. Only release-to-production.yml asks for it; a plain release route never does.
           {
             echo "<!-- release:v${NEW_VERSION} -->"
+            if [ "$DEPLOY" = "true" ]; then
+              echo "<!-- release-deploy -->"
+              echo "> Deploys to production once this merges and v${NEW_VERSION} is tagged."
+              echo
+            fi
             cat /tmp/release-notes.md
           } > /tmp/release-pr-body.md
           url=$(gh pr create \

package/loops/workflows/release-tag.yml

@@ -19,6 +19,14 @@ on:
 permissions:
   contents: write
   pull-requests: read
+  # Starting DEPLOY_WORKFLOW on the tag when the release pull request asked for a deploy.
+  actions: write
+
+env:
+  # The workflow that deploys a `v*` tag to production. Started on the new tag, with GITHUB_TOKEN,
+  # only when the release pull request carries the deploy marker (release-to-production.yml).
+  DEPLOY_WORKFLOW: app-deploy.yml
+  DEPLOY_MARKER: "<!-- release-deploy -->"
 
 concurrency:
   group: release-tag
@@ -38,6 +46,7 @@ jobs:
         with:
           persist-credentials: false
       - name: Tag the release commit and publish the GitHub Release
+        id: release
         env:
           GH_TOKEN: ${{ github.token }}
           REPO: ${{ github.repository }}
@@ -80,12 +89,19 @@ jobs:
           marker="<!-- release:${tag} -->"
           gh api "repos/$REPO/commits/$SHA/pulls" > /tmp/pulls.json
           MARKER="$marker" node -e '
-            const pulls = JSON.parse(require("fs").readFileSync("/tmp/pulls.json", "utf8"));
+            const fs = require("fs");
+            const pulls = JSON.parse(fs.readFileSync("/tmp/pulls.json", "utf8"));
             const pr = pulls.find((p) => p.merged_at && (p.body || "").includes(process.env.MARKER));
             if (!pr) process.exit(3);
-            const notes = pr.body.split(/\r?\n/).filter((line) => line.trim() !== process.env.MARKER).join("\n").trim();
-            require("fs").writeFileSync("/tmp/release-notes.md", notes + "\n");
-            console.log(`Notes from #${pr.number}`);
+            const deploy = pr.body.includes(process.env.DEPLOY_MARKER);
+            // Neither marker nor the deploy notice belongs in the published release notes.
+            const notes = pr.body.split(/\r?\n/)
+              .filter((line) => line.trim() !== process.env.MARKER && line.trim() !== process.env.DEPLOY_MARKER)
+              .filter((line) => !line.startsWith("> Deploys to production once this merges"))
+              .join("\n").trim();
+            fs.writeFileSync("/tmp/release-notes.md", notes + "\n");
+            fs.writeFileSync("/tmp/release-deploy", deploy ? "true" : "false");
+            console.log(`Notes from #${pr.number}${deploy ? ", deploy requested" : ""}`);
           ' || status=$?
 
           if [ "${status:-0}" -eq 3 ]; then
@@ -98,3 +114,30 @@ jobs:
             gh release create "$tag" --repo "$REPO" --target "$SHA" --title "$tag" --notes-file /tmp/release-notes.md
           fi
           echo "Tagged $SHA as $tag and published the GitHub Release."
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "deploy=$(cat /tmp/release-deploy 2>/dev/null || echo false)" >> "$GITHUB_OUTPUT"
+
+      # The tag above was created with GITHUB_TOKEN, so its push starts no workflow: a release does
+      # not ship by itself. A workflow_dispatch is the exception GitHub allows that token, so a
+      # release that asked for a deploy starts DEPLOY_WORKFLOW on the tag explicitly. The deploy
+      # workflow's own `pro` environment rules (required reviewers) still apply.
+      - name: Deploy the release to production
+        if: steps.release.outputs.deploy == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          TAG: ${{ steps.release.outputs.tag }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ ! -f ".github/workflows/${DEPLOY_WORKFLOW}" ]; then
+            echo "::warning::The release asked for a deploy, but .github/workflows/${DEPLOY_WORKFLOW} does not exist; $TAG was tagged and not deployed."
+            exit 0
+          fi
+          gh workflow run "$DEPLOY_WORKFLOW" --repo "$REPO" --ref "$TAG"
+          echo "Started $DEPLOY_WORKFLOW on $TAG."
+          {
+            echo "### $TAG is deploying to production"
+            echo
+            echo "Follow it in [${DEPLOY_WORKFLOW}](${GITHUB_SERVER_URL}/${REPO}/actions/workflows/${DEPLOY_WORKFLOW})."
+          } >> "$GITHUB_STEP_SUMMARY"

package/loops/workflows/release-to-production.yml

@@ -0,0 +1,50 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/release-to-production.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+name: Release to production
+# The one button for a production release, run from the repository's Actions tab (or the badge in
+# its README): Run workflow, then Run workflow again. It runs the release worker with the bump
+# chosen here and deploy=true: the worker opens the `chore(release): vX.Y.Z` pull request carrying a
+# deploy marker, it auto-merges, release-tag.yml tags it, and because of the marker starts
+# DEPLOY_WORKFLOW on the new tag, which ships to production. A `pro` environment with required
+# reviewers still asks a person before the production stage runs.
+#
+# It calls the worker directly, as the router's call-release job does, because the router's
+# workflow_dispatch is at GitHub's limit of ten inputs and has no room for a deploy flag. Running a
+# workflow by hand already requires write access to the repository, which is what the router's
+# authorize job checks. The release route on its own (Main Work Router, operation=release) is
+# unchanged: it tags and publishes a release without deploying anything.
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Version bump
+        required: true
+        type: choice
+        default: minor
+        options:
+          - minor
+          - patch
+          - major
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-to-production
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Release with a deploy
+    # AGENTIC_WORKFLOWS_DISABLED, a repository variable with any value, turns the automation off.
+    if: vars.AGENTIC_WORKFLOWS_DISABLED == ''
+    uses: ./.github/workflows/agent-release.lock.yml
+    # The caller grants what the worker requests; narrower grants make the whole run fail to start.
+    permissions: write-all
+    with:
+      version-bump: ${{ inputs.bump }}
+      deploy: "true"
+    secrets:
+      OPENAI_API_KEY: ${{ secrets.FORGE_API_KEY }}
+      # The release PR is pushed and opened with the App token so its CI runs; see the worker's conclude.
+      BOT_APP_ID: ${{ secrets.BOT_APP_ID }}
+      BOT_PRIVATE_KEY: ${{ secrets.BOT_PRIVATE_KEY }}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/workflows",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",