@plainconceptsplatform/workflows 1.12.0 → 1.13.1

package/loops/docs/diagrams.md

@@ -100,7 +100,7 @@ flowchart LR
     gate -.->|"CI failed or conflict"| fix("Fix, push, CI again") --> ci
     gate -.->|".github, secrets<br/>or 10000+ lines"| human(("Human review"))
     review("Someone reviews the PR") --> applyReview("apply-review") --> ci
-    audit("audit, weekly") -->|"files one issue"| refine
+    audit("audit, weekly") -->|"files stories"| refine
 
     classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
     classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
@@ -114,9 +114,7 @@ flowchart LR
     class merged success
 ```
 
-Audit creates work rather than consuming it, and files into `refine` rather than straight to
-`implement`, so a report of several unrelated findings becomes one properly sized issue per finding
-instead of one pull request that has to fix them all.
+Audit creates work rather than consuming it, and files into `refine` rather than straight to `implement`: one story issue per top finding, each under refine's size limit, plus a tracking report refine never sees, instead of one pull request that has to fix them all.
 
 ### The merge train
 
@@ -489,7 +487,7 @@ before anything changes. Applying them one at a time produces contradictory comm
 
 ## agent-audit.md
 
-Creates work rather than consuming it. Read-only: it files an issue and changes nothing.
+Creates work rather than consuming it. Read-only: it files a tracking report and one story issue per top finding, and changes nothing else.
 
 ```mermaid
 flowchart TD
@@ -506,8 +504,9 @@ flowchart TD
     auDedupe{"Already tracked, or<br/>previously rejected?"}
     auDedupe -.->|"all of them"| auQuiet
     auDedupe -->|"some are new"| auFile
-    auFile("One issue: every finding,<br/>top 3 refined into stories") --> auReport
-    auReport(("Filed<br/>labelled refine, so it gets<br/>sized and split per finding"))
+    auFile("Report of every finding,<br/>plus one story per top 3") --> auMeasure
+    auMeasure("conclude (rung 6)<br/>each body measured with<br/>refine's rule, trimmed to fit") --> auReport
+    auReport(("Filed<br/>report: audit, not refine<br/>stories: refine, sub-issues"))
     auQuiet(("Nothing to file<br/>the right outcome on a<br/>clean codebase"))
     auIdle(("Idle<br/>backlog already full"))
 
@@ -517,12 +516,14 @@ flowchart TD
     classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class auStart start
-    class auFacts,auRun,auScore,auFile action
+    class auFacts,auRun,auScore,auFile,auMeasure action
     class auBack,auFilter,auDedupe decision
     class auIdle idle
     class auReport,auQuiet success
 ```
 
+The report never goes to refine: refine's size gate refused every audit filed as one issue of every finding and three stories, from 2026-09-21 until 1.12.1. Each story is filed on its own, labelled `refine`, linked under the report and listed in it, so `audit-close` closes the report once its stories are closed. A story already tracked by an open issue is listed against that issue instead of filed again.
+
 Memory matters here: open issues only cover what is still open, so a finding reported weeks ago and
 consciously not acted on would come back every single run. The audit records its dispositions and
 reads them next time.
@@ -549,8 +550,9 @@ flowchart TD
     daDedupe{"New finding, proven<br/>on both sides?"}
     daDedupe -.->|"none left"| daQuiet
     daDedupe -->|"some"| daFile
-    daFile("One issue with<br/>evidence per finding") --> daReport
-    daReport(("Filed<br/>labelled docs-audit and refine,<br/>sized and split per finding"))
+    daFile("Report of every finding,<br/>plus one story per top 3") --> daMeasure
+    daMeasure("conclude (rung 6)<br/>each body measured with<br/>refine's rule, trimmed to fit") --> daReport
+    daReport(("Filed<br/>report: docs-audit, not refine<br/>stories: refine, sub-issues"))
     daQuiet(("Nothing to file<br/>the documentation is current"))
     daIdle(("Idle<br/>no agent, no spend"))
 
@@ -560,7 +562,7 @@ flowchart TD
     classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class daStart start
-    class daFacts,daRun,daFile action
+    class daFacts,daRun,daFile,daMeasure action
     class daBack,daMoved,daDedupe decision
     class daIdle idle
     class daReport,daQuiet success
@@ -569,6 +571,8 @@ flowchart TD
 Reports join the audit chain: `audit-close` closes one when its children are closed, and marks it
 `stale-audit` when nobody acted on it, which frees the slot.
 
+It files the way the audit does, through the same `file-audit-issues` step: the report never goes to refine, which refused a single report of every finding once it grew past its size gate. Each top story is filed on its own, labelled `refine`, linked under the report and listed in it.
+
 ---
 
 ## agent-release.md
@@ -652,7 +656,8 @@ flowchart TB
     hkBranch -->|yes| hkDelete("Delete the branch")
     hkBranch -.->|"open PR, human PR,<br/>or the default branch"| hkDigest
     hkDelete --> hkDigest
-    hkDigest("Rewrite one issue:<br/>Needs a human") --> hkEnd
+    hkDigest("Rewrite one issue:<br/>Needs a human") --> hkDependabot
+    hkDependabot("Squash-merge Dependabot PRs<br/>whose checks are all green") --> hkEnd
     hkEnd(("One place to look<br/>instead of four repos"))
 
     classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
@@ -660,7 +665,7 @@ flowchart TB
     classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class hkCron start
-    class hkScan,hkRetry,hkStrand,hkParent,hkDelete,hkDigest,hkStackClose action
+    class hkScan,hkRetry,hkStrand,hkParent,hkDelete,hkDigest,hkStackClose,hkDependabot action
     class hkPark,hkWhy,hkBudget,hkBranch,hkStack,hkStackWait decision
     class hkEnd success
 ```
@@ -681,6 +686,8 @@ held for days after its announcement, a root closed by accident with children op
 root pull request each get one line in the digest. No labels move, so nothing the router listens
 for is raised by the sweep itself.
 
+The last step merges Dependabot's updates through the `merge-dependabot` action: only pull requests Dependabot opened with every commit verified and its own, squash-merged once every check is green, a stale one asked once to rebase, a failing one listed in the job summary. It reads nothing of the pull request but the API, and `DEPENDABOT_MERGE` sets its scope. See `docs/dependabot-merge.md` in the package.
+
 ---
 
 ## agentics-app-errors

package/loops/templates/ci/app-ci-dotnet-next.yml

@@ -963,6 +963,9 @@ jobs:
   # If a deploy pipeline calls this workflow with `uses:`, that caller must also grant
   # `actions: write`. A called workflow may not request a scope its caller withheld, and the
   # whole run fails to start with zero jobs and no annotation when it does.
+  #
+  # Not for Dependabot: its runs get a read-only token, so the dispatch would fail its pull request,
+  # and the router's maintenance run merges Dependabot updates instead of the train.
   dispatch-merge-gate:
     name: Dispatch merge gate
     needs: [api, mutation-api, web, mutation-web, secret-scan, deps-and-iac-scan, sast-scan, sbom, engineering-excellence, platform-conformance, full-ci]
@@ -972,6 +975,7 @@ jobs:
       github.event_name == 'pull_request' &&
       github.event.pull_request.head.repo.full_name == github.repository &&
       github.event.pull_request.draft == false &&
+      github.event.pull_request.user.login != 'dependabot[bot]' &&
       (github.event.pull_request.user.login == 'app/github-actions' || endsWith(github.event.pull_request.user.login, '[bot]'))
     runs-on: ${{ vars.CI_RUNNER || 'agents-arc' }}
     timeout-minutes: 5

package/loops/templates/ci/app-ci-node-monorepo.yml

@@ -239,6 +239,9 @@ jobs:
   # If a deploy pipeline calls this workflow with `uses:`, that caller must also grant
   # `actions: write`. A called workflow may not request a scope its caller withheld, and the
   # whole run fails to start with zero jobs and no annotation when it does.
+  #
+  # Not for Dependabot: its runs get a read-only token, so the dispatch would fail its pull request,
+  # and the router's maintenance run merges Dependabot updates instead of the train.
   dispatch-merge-train:
     name: Dispatch merge train
     needs: [lint, web, mutation-web, e2e, desktop, mobile]
@@ -246,7 +249,8 @@ jobs:
       always() &&
       github.event_name == 'pull_request' &&
       github.event.pull_request.head.repo.full_name == github.repository &&
-      github.event.pull_request.draft == false
+      github.event.pull_request.draft == false &&
+      github.event.pull_request.user.login != 'dependabot[bot]'
     runs-on: agents-arc
     timeout-minutes: 5
     permissions:

package/loops/templates/dependabot-merge/.github/workflows/dependabot-merge.yml

@@ -0,0 +1,80 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/templates/dependabot-merge/.github/workflows/dependabot-merge.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+name: "Dependabot: Merge"
+
+# Every six hours, squash-merges the open Dependabot pull requests whose checks are all green, for a
+# repository that does not run the work router (the router does the same in its maintenance run).
+# Plain YAML, no model, and the pull request's code is never checked out: the checkout below is the
+# default branch, for the action. Only pull requests Dependabot opened, with every commit
+# Dependabot's, are touched. See docs/dependabot-merge.md in agentic-workflows.
+#
+# With the Platform App secrets (BOT_APP_ID / BOT_PRIVATE_KEY) the merge runs as the App, and the
+# merge commit starts the default branch's push workflows. Without them it runs as GITHUB_TOKEN,
+# and GitHub starts no workflow from a merge made with that token: nothing deploys on push until
+# the next commit that is not a Dependabot merge.
+#
+# To turn it off: set DEPENDABOT_MERGE to "off" below, or the repository variable DEPENDABOT_MERGE
+# to "off", or AGENTIC_WORKFLOWS_DISABLED to anything, or delete this file.
+on:
+  schedule:
+    - cron: "41 */6 * * *"
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: "Decide and report, merge nothing"
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: dependabot-merge
+  cancel-in-progress: false
+
+env:
+  # "all", "minor" (minor and patch), "patch", or "off". CI is the gate.
+  DEPENDABOT_MERGE: "all"
+  # "true" also merges in a repository with no checks at all, once the head is an hour old.
+  DEPENDABOT_MERGE_WITHOUT_CHECKS: "true"
+
+jobs:
+  merge:
+    name: Merge Dependabot pull requests
+    if: "!github.event.repository.fork && vars.AGENTIC_WORKFLOWS_DISABLED == ''"
+    runs-on: ${{ vars.CI_RUNNER || 'ubuntu-latest' }}
+    timeout-minutes: 15
+    permissions:
+      # Merging, deleting the merged branch, approving where a ruleset asks for it, and commenting
+      # `@dependabot rebase`. All of it through the API. checks and statuses: the reads run on
+      # this token, since the App installation may hold no Checks permission.
+      contents: write
+      pull-requests: write
+      issues: write
+      checks: read
+      statuses: read
+    env:
+      HAS_APP: ${{ secrets.BOT_APP_ID != '' && secrets.BOT_PRIVATE_KEY != '' }}
+    steps:
+      - name: Checkout the action
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          sparse-checkout: .github/actions/merge-dependabot
+
+      - name: Generate App token
+        id: app-token
+        if: env.HAS_APP == 'true'
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_PRIVATE_KEY }}
+
+      - uses: ./.github/actions/merge-dependabot
+        with:
+          token: ${{ steps.app-token.outputs.token || github.token }}
+          read-token: ${{ github.token }}
+          scope: ${{ vars.DEPENDABOT_MERGE || env.DEPENDABOT_MERGE }}
+          merge-without-checks: ${{ env.DEPENDABOT_MERGE_WITHOUT_CHECKS }}
+          post-merge-event: ""
+          dry-run: ${{ github.event.inputs.dry-run || 'false' }}

package/loops/workflows/agent-audit.md

@@ -19,15 +19,23 @@ env:
   # One line: gh-aw joins a multi-line env value onto a single line when it compiles the lock.
   AUDIT_FOCUS: "Architectural layer violations and dependencies pointing the wrong way. Missing or misleading tests around behaviour that already shipped. Security gaps: unvalidated input, missing authorization, secrets in code. Performance anti-patterns, N+1 queries in particular. Documentation that no longer matches the code it describes."
   AUDIT_MARKER: "<!-- agent-audit -->"
+  # The largest issue the audit files, measured with refine's own rule (issue-size.cjs). Three
+  # quarters of agent-refine.md's REFINE_MAX_BODY_CHARS and REFINE_MAX_WORK_UNITS, so a story a
+  # person edits a little still refines. A body over these is trimmed before it is filed.
+  AUDIT_MAX_BODY_CHARS: "6000"
+  AUDIT_MAX_WORK_UNITS: "18"
+  AUDIT_MAX_STORIES: "3"
   GIT_AUTHOR_NAME: "github-actions[bot]"
   GIT_AUTHOR_EMAIL: "github-actions[bot]@users.noreply.github.com"
   GIT_COMMITTER_NAME: "github-actions[bot]"
   GIT_COMMITTER_EMAIL: "github-actions[bot]@users.noreply.github.com"
 description: |
-  Read-only repository audit. Finds 5-7 problems, scores each 1-10, files a single issue
-  with all findings listed and the top 3 refined as actionable user stories. The issue is
-  labelled `audit` + `bug` + `refine`, so Refine sizes it and splits a multi-defect report
-  into one estimated issue per finding rather than one pull request that has to fix them all. Replaces .loops/recipes/guardrails-audit-loop.yaml.
+  Read-only repository audit. Finds 5-7 problems, scores each 1-10, and files a compact
+  tracking report of every finding, labelled `audit` + `bug`, plus one story issue for each of
+  the top 3, labelled `bug` + `refine` and linked to the report as sub-issues. Refine refines
+  each story on its own; the report never goes to Refine. Every body is measured with refine's
+  size rule before it is filed and trimmed to fit, because one issue holding every finding and
+  three stories was over refine's limit every time and was refused. Replaces .loops/recipes/guardrails-audit-loop.yaml.
 
   Router-only worker: triggered exclusively via workflow_call from work-router.yml.
   Contract input: trigger-kind(scheduled|manual).
@@ -54,7 +62,8 @@ on:
         type: string
         default: manual
 
-  # Rung 1. Do not pile reports on top of unactioned reports.
+  # Rung 1. Do not pile reports on top of unactioned reports. Only the report carries `audit`;
+  # its stories do not, or one audit would fill the three slots by itself.
   #
   # `-label:stale-audit` is what keeps this backpressure from becoming a stop. Three reports
   # nobody ever actioned used to disable the weekly audit for good: the query counted them
@@ -115,19 +124,27 @@ jobs:
         with:
           client-id: ${{ secrets.BOT_APP_ID }}
           private-key: ${{ secrets.BOT_PRIVATE_KEY }}
-      # No apply-agent-output here. The safe_outputs job already created the issue and
-      # exposes its number; calling the action with create-issues would file a second copy
-      # of the same report. It was only needed while staged: true suppressed the native
-      # write, and staged is gone.
-      - name: Apply audit labels to created issues
-        if: needs.safe_outputs.outputs.created_issue_number != ''
-        uses: ./.github/actions/add-issue-labels
+      # Staged, so this is the only write: the report, then each story with its labels and a
+      # link back, then the report's list of stories. Each body passes refine's size rule first.
+      - name: Download agent output
+        id: output
+        uses: ./.github/actions/download-agent-output
         with:
+          artifact-name: ${{ needs.activation.outputs.artifact_prefix }}agent
+      - name: File the report and its stories
+        uses: ./.github/actions/file-audit-issues
+        with:
+          output-file: ${{ steps.output.outputs.output-file }}
           token: ${{ steps.app-token.outputs.token }}
-          issue-number: ${{ needs.safe_outputs.outputs.created_issue_number }}
-          labels: |
+          max-body-chars: ${{ env.AUDIT_MAX_BODY_CHARS }}
+          max-work-units: ${{ env.AUDIT_MAX_WORK_UNITS }}
+          max-stories: ${{ env.AUDIT_MAX_STORIES }}
+          run-url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          report-labels: |-
             audit
             bug
+          story-labels: |-
+            bug
             refine
 
   # An audit that produced nothing reported success. The whole run -- a full agent, its tokens,
@@ -138,7 +155,7 @@ jobs:
   #
   # This fires when the agent succeeded and the safe-outputs handler processed nothing at all.
   #
-  # Step 6 of the prompt gives a clean codebase its own outcome -- call `noop` and stop -- and
+  # Step 7 of the prompt gives a clean codebase its own outcome -- call `noop` and stop -- and
   # that outcome must not be reported as a failure. `noop` is a registered safe output here
   # (`noop: max 1`), so the handler receives it as a message and the processed count is not zero,
   # which keeps a deliberately empty audit out of this branch. That is read from the handler
@@ -171,8 +188,11 @@ safe-outputs:
   # under noise nobody closes.
   report-failure-as-issue: false
   threat-detection: false
+  # The report and the stories are filed by `conclude`, after they are measured.
+  staged: true
+  # The report and up to three stories.
   create-issue:
-    max: 1
+    max: 4
 
 # The fleet is two machines, so this clock is also how long a stuck run can hold half of it.
 # 240 went on to every worker at once when the provider was slow, which fixed the deaths and
@@ -227,21 +247,18 @@ timeout-minutes: 90
    again. What this prevents is re-filing something the team looked at and chose to live
    with, which is the noise that makes an audit backlog get ignored.
 
-5. Call `create_issue` **once** with title "Audit: <date>". Do NOT specify labels , the
-   conclude job will apply them. The body MUST have two sections:
+5. File the report: call `create_issue` with title "Audit: <YYYY-MM-DD>" and nothing else in the title. Do NOT specify labels; the conclude job applies them. The report is a compact tracking list, not a story: Refine never reads it. One entry per finding, highest score first, each exactly this shape and no longer than about 600 characters:
 
-   **Section 1 , All findings:** A numbered list of every finding (5-7) with its score,
-   file path, and a one-line description. Order by score descending.
+   ```
+   ### <n>. <one-line problem> (score <s>)
+   **Where:** `path/to/file.ext:line`, `other/file.ext:line`
+   **Problem:** One or two sentences: what happens and its impact.
+   **Fix:** One or two sentences: the change that resolves it.
+   ```
 
-   **Section 2 , Top 3 to implement:** Call skill("pc-plan-story") and refine the top 3
-   findings by score into user stories; that skill owns their shape. Name the likely files to
-   change. Mark this section clearly with a heading like `## Top 3 , To Implement`.
+   No bullet lists, no Gherkin, no user stories, no reproduction walkthroughs. Do not write any issue number (`#123`) in the report: the workflow adds the links to the stories, and every number in it is read as work the report waits on.
 
-   The issue you file goes to Refine, not straight to implementation. Refine sizes it and,
-   because a report of several unrelated defects across different files is exactly the shape
-   that does not land as one pull request, splits it into one properly estimated issue per
-   finding. Write each finding so it survives that split: self-contained, naming its own
-   files and its own acceptance criteria, never "as above" or "same as finding 2".
+6. File the stories: call skill("pc-plan-story") and write the top ${{ env.AUDIT_MAX_STORIES }} findings by score as user stories; that skill owns their shape. Call `create_issue` once per story, after the report, titled with the story's own title (never "Audit: ..."), no labels. Refine refines each story on its own, so each must stand alone: it names its own files and its own acceptance criteria, never "as above" or "see finding 2", and never mentions the other stories or the report. Keep each story well under ${{ env.AUDIT_MAX_BODY_CHARS }} characters and ${{ env.AUDIT_MAX_WORK_UNITS }} bullet lines: the workflow measures every issue against that limit before filing and cuts anything over it from the end.
 
-6. If nothing met the bar, call `noop` and stop. Filing nothing is the right outcome when
+7. If nothing met the bar, call `noop` and stop. Filing nothing is the right outcome when
    the codebase is clean.

package/loops/workflows/agent-docs-audit.md

@@ -19,15 +19,23 @@ env:
   # No commit in this many days means nothing can have drifted since the last run, so a scheduled
   # run stops before the model starts. 17 is the longest gap between runs on days 1 and 15.
   DOCS_AUDIT_QUIET_DAYS: "17"
+  # The largest issue the docs audit files, measured with refine's own rule (issue-size.cjs), as
+  # agent-audit.md does: three quarters of refine's limits. A body over these is trimmed first.
+  DOCS_AUDIT_MAX_BODY_CHARS: "6000"
+  DOCS_AUDIT_MAX_WORK_UNITS: "18"
+  DOCS_AUDIT_MAX_STORIES: "3"
   GIT_AUTHOR_NAME: "github-actions[bot]"
   GIT_AUTHOR_EMAIL: "github-actions[bot]@users.noreply.github.com"
   GIT_COMMITTER_NAME: "github-actions[bot]"
   GIT_COMMITTER_EMAIL: "github-actions[bot]@users.noreply.github.com"
 description: |
   Read-only documentation audit. Checks that the repository's documentation still matches its
-  code and the Platform documentation standard. When it does not, files a single issue of
-  findings with evidence from both sides, labelled `docs-audit` + `refine`, so Refine sizes it
-  and splits it into one issue per finding. When the documentation is current, files nothing.
+  code and the Platform documentation standard. When it does not, files a compact tracking report
+  of every finding, labelled `docs-audit` and never `refine`, plus one story issue for each of the
+  top 3 findings, labelled `documentation` + `refine` and linked to the report as sub-issues.
+  Every body is measured with refine's size rule before it is filed and trimmed to fit, because a
+  single report of every finding grows past refine's limit and is refused. When the documentation
+  is current, files nothing.
 
   Router-only worker: triggered exclusively via workflow_call from work-router.yml.
   Contract input: trigger-kind(scheduled|manual).
@@ -173,16 +181,27 @@ jobs:
         with:
           client-id: ${{ secrets.BOT_APP_ID }}
           private-key: ${{ secrets.BOT_PRIVATE_KEY }}
-      # The safe_outputs job already created the issue. Only the labels are left, and they are
-      # applied with the App token so that `refine` reaches the router as a trusted event.
-      - name: Apply labels to the report
-        if: needs.safe_outputs.outputs.created_issue_number != ''
-        uses: ./.github/actions/add-issue-labels
+      # Staged, so this is the only write, as in agent-audit.md: the report, each story with its
+      # labels and a link back, then the report's list. The App token lets `refine` reach the router.
+      - name: Download agent output
+        id: output
+        uses: ./.github/actions/download-agent-output
         with:
+          artifact-name: ${{ needs.activation.outputs.artifact_prefix }}agent
+      - name: File the report and its stories
+        uses: ./.github/actions/file-audit-issues
+        with:
+          output-file: ${{ steps.output.outputs.output-file }}
           token: ${{ steps.app-token.outputs.token }}
-          issue-number: ${{ needs.safe_outputs.outputs.created_issue_number }}
-          labels: |
+          max-body-chars: ${{ env.DOCS_AUDIT_MAX_BODY_CHARS }}
+          max-work-units: ${{ env.DOCS_AUDIT_MAX_WORK_UNITS }}
+          max-stories: ${{ env.DOCS_AUDIT_MAX_STORIES }}
+          run-url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          report-title: '^docs audit:'
+          report-labels: |-
             docs-audit
+          story-labels: |-
+            documentation
             refine
 
   # An agent that ended without a report or a noop would otherwise be a green run that audited
@@ -208,8 +227,11 @@ safe-outputs:
   # A failed run is already a red run. An issue per failure buries the real backlog.
   report-failure-as-issue: false
   threat-detection: false
+  # The report and the stories are filed by `conclude`, after they are measured.
+  staged: true
+  # The report and up to three stories.
   create-issue:
-    max: 1
+    max: 4
 
 # Reads documents and the code they describe, and writes one issue. Unobserved so far: audit, the
 # nearest worker, takes about 45 minutes over a whole repository, and this one reads less.
@@ -253,14 +275,18 @@ timeout-minutes: 60
 7. If no finding is left, call `noop` and stop. Filing nothing is the right outcome when the
    documentation is current.
 
-8. Call `create_issue` **once** with title "Docs audit: <date>". Do NOT specify labels, the
-   conclude job applies them. List every finding, the most misleading first, each with:
-   - the document's `file:line` and the stale statement;
-   - the evidence from the code, with its `file:line` or path;
-   - what the document should say, or the section that has to be added.
+8. File the report: call `create_issue` with title "Docs audit: <YYYY-MM-DD>" and nothing else in the title. Do NOT specify labels; the conclude job applies them. The report is a compact tracking list, not a story: Refine never reads it. One entry per finding, the most misleading first, each exactly this shape and no longer than about 600 characters:
+
+   ```
+   ### <n>. <one-line stale statement>
+   **Document:** `path/to/doc.md:line`, what it says
+   **Evidence:** `path/to/code.ext:line` or the path that shows otherwise
+   **Fix:** What the document should say, or the section that has to be added.
+   ```
+
+   No bullet lists and no user stories. Do not write any issue number (`#123`) in the report: the workflow adds the links to the stories, and every number in it is read as work the report waits on.
 
-   The issue goes to Refine, which sizes it and splits it into one issue per finding, so write
-   each finding to survive that: self-contained, naming its own files, never "as above".
+9. File the stories: write the top ${{ env.DOCS_AUDIT_MAX_STORIES }} findings as short stories. Call `create_issue` once per story, after the report, titled with what the story fixes (never "Docs audit: ..."), no labels. Refine refines each story on its own, so each must stand alone: it names its document and the code that contradicts it, says what the document should say, and never says "as above" or mentions the other stories or the report. Keep each story well under ${{ env.DOCS_AUDIT_MAX_BODY_CHARS }} characters and ${{ env.DOCS_AUDIT_MAX_WORK_UNITS }} bullet lines: the workflow measures every issue against that limit before filing and cuts anything over it from the end.
 
    Refer to people by role, never by name, and include no personal contact details, even when
    a document you are quoting contains them.

package/loops/workflows/agent-refine.md

@@ -47,7 +47,8 @@ env:
   # one, Pliny-Bot #305 (13,398 chars, 92 work units), burned a full agent -- 17 minutes,
   # 2.4M tokens -- and died at the provider's 32K output cap with zero outcome, twice.
   # Both numbers are measured before the agent starts, so refusal is deterministic and
-  # costs ten seconds instead of half an hour.
+  # costs ten seconds instead of half an hour. The audit files under its own AUDIT_MAX_*,
+  # which must stay below these or refine refuses what it files.
   REFINE_MAX_BODY_CHARS: "8000"
   REFINE_MAX_WORK_UNITS: "24"
   REFUSE_MARKER: "<!-- agent-refine-refused -->"
@@ -207,9 +208,8 @@ jobs:
   # The size gate, rung 4. Measures the issue before any model starts, because an oversized
   # body does not fail fast on its own: it produces an agent that explores for seventeen
   # minutes and then dies mid-generation at the provider's response cap having written
-  # nothing, which reads as a green run with no outcome (Pliny-Bot #305, twice). Pure
-  # shell, no network beyond one issue read; over either limit it is a refusal, not a
-  # smaller attempt.
+  # nothing, which reads as a green run with no outcome (Pliny-Bot #305, twice). No
+  # model, one issue read; over either limit it is a refusal, not a smaller attempt.
   size_guard:
     needs: [still_open, eligibility]
     if: needs.still_open.outputs.open == 'true' && needs.eligibility.outputs.eligible == 'true'
@@ -219,36 +219,23 @@ jobs:
       contents: read
       issues: read
     outputs:
-      too_big: ${{ steps.measure.outputs.too_big }}
+      too_big: ${{ steps.measure.outputs.too-big }}
       reason: ${{ steps.measure.outputs.reason }}
     steps:
+      - name: Checkout workflow actions
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      # The rule lives in issue-size.cjs, which the audit also runs before it files, so the two
+      # cannot drift: every audit report from 2026-09-21 on was refused here for want of it.
       - name: Measure the issue against the size limits
         id: measure
-        env:
-          GH_TOKEN: ${{ github.token }}
-          REPO: ${{ github.repository }}
-          ISSUE_NUMBER: ${{ inputs.issue-number }}
-          MAX_BODY_CHARS: ${{ env.REFINE_MAX_BODY_CHARS }}
-          MAX_WORK_UNITS: ${{ env.REFINE_MAX_WORK_UNITS }}
-        run: |
-          set -euo pipefail
-          body=$(gh issue view "$ISSUE_NUMBER" --repo "$REPO" --json title,body --jq '.title + "\n\n" + (.body // "")')
-          chars=$(printf '%s' "$body" | wc -c)
-          # One work unit per markdown bullet, the same split the prompt's step 3 makes.
-          units=$(printf '%s' "$body" | grep -cE '^[[:space:]]*[-*] ' || true)
-          reason=""
-          too_big=false
-          if [ "$chars" -gt "$MAX_BODY_CHARS" ]; then
-            too_big=true
-            reason="body ${chars} chars > ${MAX_BODY_CHARS}"
-          fi
-          if [ "$units" -gt "$MAX_WORK_UNITS" ]; then
-            too_big=true
-            reason="${reason:+$reason; }work units ${units} > ${MAX_WORK_UNITS}"
-          fi
-          echo "too_big=$too_big" >> "$GITHUB_OUTPUT"
-          echo "reason=$reason" >> "$GITHUB_OUTPUT"
-          echo "::notice::measured $chars chars, $units work units (limits: ${MAX_BODY_CHARS} chars, ${MAX_WORK_UNITS} units) -> $too_big"
+        uses: ./.github/actions/measure-issue-size
+        with:
+          token: ${{ github.token }}
+          issue-number: ${{ inputs.issue-number }}
+          max-body-chars: ${{ env.REFINE_MAX_BODY_CHARS }}
+          max-work-units: ${{ env.REFINE_MAX_WORK_UNITS }}
   # The deterministic refusal. Runs only when the size gate tripped, so it costs one
   # comment and no model. The refine label stays: a human who shrinks the body and
   # replies re-enters rerefine through the comment route, and the classifier ignores

package/loops/workflows/work-router.yml

@@ -151,6 +151,14 @@ env:
   # The single issue that lists what genuinely needs a person. Set it empty to turn the digest
   # off and keep the rest of the janitor.
   HOUSEKEEPING_DIGEST_TITLE: "Needs a human"
+  # Which Dependabot pull requests the six-hourly maintenance squash-merges once every check is
+  # green: "all", "minor" (minor and patch), "patch", or "off". CI is the gate; only pull requests
+  # Dependabot opened, with every commit Dependabot's, are touched. A repository variable of the
+  # same name overrides this without a commit.
+  DEPENDABOT_MERGE: "all"
+  # "true" also merges a Dependabot pull request in a repository with no checks at all, once its
+  # head is an hour old. "false" leaves those for a person.
+  DEPENDABOT_MERGE_WITHOUT_CHECKS: "true"
   # How long an audit report may sit open before it is labelled `stale-audit`. The audit's own
   # backpressure ignores a stale report, so three abandoned reports can no longer disable the
   # weekly audit for good; the digest lists them instead. Two missed weekly cycles.
@@ -1827,6 +1835,9 @@ jobs:
       pull-requests: read
       # actions: write cancels workflow runs stuck pending in the fleet queue.
       actions: write
+      # The Dependabot merge reads check runs and statuses with this token, not the App's.
+      checks: read
+      statuses: read
     env:
       BOT_APP_ID: ${{ secrets.BOT_APP_ID }}
       BOT_PRIVATE_KEY: ${{ secrets.BOT_PRIVATE_KEY }}
@@ -1852,6 +1863,18 @@ jobs:
           stale-pr-days: ${{ env.HOUSEKEEPING_STALE_PR_DAYS }}
           digest-title: ${{ env.HOUSEKEEPING_DIGEST_TITLE }}
           dry-run: ${{ github.event.inputs.dry-run || 'false' }}
+      # Dependabot updates merge here rather than on a cron of their own. API calls only: no pull
+      # request code is checked out. It runs even when the sweep above failed.
+      - name: Merge Dependabot pull requests
+        if: ${{ !cancelled() && steps.app-token.outcome == 'success' }}
+        uses: ./.github/actions/merge-dependabot
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          read-token: ${{ github.token }}
+          scope: ${{ vars.DEPENDABOT_MERGE || env.DEPENDABOT_MERGE }}
+          merge-without-checks: ${{ env.DEPENDABOT_MERGE_WITHOUT_CHECKS }}
+          skip-labels: do-not-merge blocked human-review ${{ env.MERGE_TRAIN_HOLD_LABEL }}
+          dry-run: ${{ github.event.inputs.dry-run || 'false' }}
 
   validate:
     needs: classify

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/workflows",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",
@@ -41,6 +41,6 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.8.0",
-    "vitest": "^3.0.0"
+    "vitest": "^4.1.11"
   }
 }