@plainconceptsplatform/workflows 1.11.0 → 1.13.0

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.
@@ -1852,6 +1860,17 @@ 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 }}
+          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.11.0",
+  "version": "1.13.0",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",