@plainconceptsplatform/workflows 1.11.0 → 1.13.0

package/README.md

@@ -81,7 +81,7 @@ npx --yes --package @plainconceptsplatform/workflows@latest workflows search "ci
 
 ## Templates
 
-Install optional standalone templates with `add --template`. Available templates are `agentics-checks`, `agentics-error-report`, `agentics-maintenance`, `app-ci-dotnet-next`, `app-ci-node-monorepo`, `bug-report`, `feature-request`, `github-release`, `opencode.ci.json`, `platform-template` and `quality-gates`. CI templates are stack-specific copies, not a combined template. `quality-gates` and `platform-template` are bundles for the platform family: they stay package-managed and `update` refreshes them where they are installed; see `docs/family-templates.md` in the repository. `github-release` publishes generated release notes when a `v*` tag is pushed. Edit their top-level `env:` values for repository paths, package names, and commands.
+Install optional standalone templates with `add --template`. Available templates are `agentics-checks`, `agentics-error-report`, `agentics-maintenance`, `app-ci-dotnet-next`, `app-ci-node-monorepo`, `bug-report`, `feature-request`, `github-release`, `opencode.ci.json`, `platform-template` and `quality-gates`. CI templates are stack-specific copies, not a combined template. `quality-gates` and `platform-template` are bundles: they stay package-managed and `update` refreshes them where they are installed. `platform-template` reads the platform contract, `.platform/contract.yml`; see `docs/platform-contracts.md` and `docs/family-templates.md` in the repository. `github-release` publishes generated release notes when a `v*` tag is pushed. Edit their top-level `env:` values for repository paths, package names, and commands.
 
 `agentics-error-report` is worth installing everywhere. Once a day it classifies how *this package's* workflows behaved in the repository and files what broke upstream, so the package gets fixed instead of every repository working around the same bug. It is deterministic no model runs, because a model asked to summarise a failure paraphrases whatever the log held and it sends only the names this package gives its own workflows, jobs and steps, a conclusion, a bucketed runner label, a count and a classification id. No log line, branch, title, path or issue number leaves the repository, the repository's own workflows are counted and never inspected, and a leak scanner withholds any report mentioning the repository or its owner and fails the run rather than filing it. Clear `UPSTREAM_NAME` in its `env:` to compute the report into the job summary and file nothing.
 

package/dist/index.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import { inspectRepository, parseVisibility, resolveVisibility } from "./repository-inspection.js";
-import { catalogSourcePath, installCatalog, installedRoutes, installTemplate, isTemplateName, removeRouteFiles } from "./catalog-installation.js";
+import { catalogSourcePath, exists, installCatalog, installedRoutes, installTemplate, isTemplateName, removeRouteFiles } from "./catalog-installation.js";
 import { installBundle, installedBundles, isBundleTemplate } from "./template-bundles.js";
 import { formatCatalog, listCatalog, searchCatalog } from "./catalog-listing.js";
 import { packageVersion } from "./package-baseline.js";
 import { routeNames, templateNames } from "./workflow-catalog.js";
 import { runInteractive } from "./tui.js";
 import { realpathSync } from "node:fs";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 const HELP_TEXT = `Workflows CLI install and update Plain Concepts Platform agentic workflows.
 
@@ -125,9 +125,19 @@ export async function run(arguments_, repositoryPath = process.cwd()) {
         const sourcePath = catalogSourcePath();
         // The installed set is always part of the target set: adding a route never drops another,
         // and a plain update refreshes exactly what is there, bundle templates included. A bundle
-        // nobody installed is never added by an update.
-        if (routes.length > 0 || template === undefined) {
-            const selectedRoutes = unionRoutes(routes, await installedRoutes(repositoryPath));
+        // nobody installed is never added by an update, and a repository holding only bundles gets
+        // no router from one.
+        const installedRouteSet = await installedRoutes(repositoryPath);
+        const routerInstalled = await exists(join(repositoryPath, ".github", "workflows", "work-router.yml"));
+        const bundlesOnly = command === "update" && routes.length === 0 && template === undefined &&
+            installedRouteSet.length === 0 && !routerInstalled && (await installedBundles(repositoryPath, sourcePath)).length > 0;
+        if (bundlesOnly) {
+            for (const name of await installedBundles(repositoryPath, sourcePath)) {
+                bundles.push(await installBundle(repositoryPath, name, sourcePath, { force, dryRun }));
+            }
+        }
+        else if (routes.length > 0 || template === undefined) {
+            const selectedRoutes = unionRoutes(routes, installedRouteSet);
             catalog = await installCatalog(repositoryPath, { force, dryRun, selectedRoutes, inspection, baseline });
             allConflicts.push(...catalog.conflicts);
             allInstalled.push(...catalog.installed);
@@ -137,6 +147,9 @@ export async function run(arguments_, repositoryPath = process.cwd()) {
             }
         }
         if (template !== undefined && isBundleTemplate(template)) {
+            if (template === "dependabot-merge" && routerInstalled) {
+                console.error("warning: the work router already merges Dependabot pull requests in its maintenance run; this workflow does the same work twice.");
+            }
             bundles.push(await installBundle(repositoryPath, template, sourcePath, { force, dryRun }));
         }
         else if (template !== undefined) {

package/dist/template-bundles.js

@@ -30,13 +30,13 @@ export async function installedBundles(repositoryPath, sourcePath) {
 }
 export async function installBundle(repositoryPath, template, sourcePath, options = {}) {
     const version = options.packageVersion ?? await packageVersion();
-    const root = bundleRoot(sourcePath, template);
-    const targets = await bundleTargets(sourcePath, template);
+    const files = await bundleFiles(sourcePath, template);
+    const targets = files.map((file) => file.target);
     const changes = [];
     const writes = [];
-    for (const target of targets) {
+    for (const { source, target } of files) {
         const current = await readOptional(join(repositoryPath, target));
-        const text = stampVersion(normalizeEol(await readFile(join(root, target), "utf8")), version);
+        const text = stampVersion(normalizeEol(await readFile(source, "utf8")), version);
         const recorded = current === undefined ? undefined : installedVersion(current);
         const base = recorded === undefined ? { target } : { target, installedVersion: recorded };
         if (current === text) {
@@ -89,6 +89,20 @@ function bundleRoot(sourcePath, template) {
         throw new Error(`${template} is not a bundle template`);
     return join(sourcePath, "templates", entry.directory);
 }
+// The bundle's own files, then the actions it borrows from the catalog. Only the former decide whether
+// it is installed: a router consumer carries the same actions without having asked for the bundle.
+async function bundleFiles(sourcePath, template) {
+    const root = bundleRoot(sourcePath, template);
+    const own = (await bundleTargets(sourcePath, template)).map((target) => ({ source: join(root, target), target }));
+    const borrowed = [];
+    for (const action of catalogTemplates.find((item) => item.name === template)?.actions ?? []) {
+        const directory = join(sourcePath, "actions", action);
+        for (const file of (await readdir(directory)).sort()) {
+            borrowed.push({ source: join(directory, file), target: `.github/actions/${action}/${file}` });
+        }
+    }
+    return [...own, ...borrowed].sort((left, right) => (left.target < right.target ? -1 : left.target > right.target ? 1 : 0));
+}
 async function bundleTargets(sourcePath, template) {
     const root = bundleRoot(sourcePath, template);
     const entries = await readdir(root, { recursive: true, withFileTypes: true });

package/dist/workflow-catalog.d.ts

@@ -19,7 +19,7 @@ export interface MandatoryFile {
 }
 export declare const mandatoryFiles: readonly MandatoryFile[];
 export declare const generatedConsumerTargets: readonly [".github/workflows/agent-*.lock.yml", ".github/aw/actions-lock.json"];
-export declare const templateNames: readonly ["agentics-app-errors", "agentics-checks", "agentics-error-report", "agentics-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "bug-report", "feature-request", "github-release", "opencode.ci.json", "platform-template", "quality-gates"];
+export declare const templateNames: readonly ["agentics-app-errors", "agentics-checks", "agentics-error-report", "agentics-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "bug-report", "dependabot-merge", "feature-request", "github-release", "opencode.ci.json", "platform-template", "quality-gates"];
 export type TemplateName = (typeof templateNames)[number];
 export interface CatalogTemplate {
     readonly name: TemplateName;
@@ -30,6 +30,8 @@ export interface CatalogTemplate {
     readonly directory?: string;
     /** Several files under `templates/<directory>/`, package-managed and refreshed by `update` where installed. */
     readonly bundle?: boolean;
+    /** Actions from `actions/` a bundle installs under `.github/actions/`, for a repository without the router. */
+    readonly actions?: readonly string[];
 }
 export declare const catalogTemplates: readonly CatalogTemplate[];
 /** Bundle templates: several package-managed files, refreshed by `update` where installed. */

package/dist/workflow-catalog.js

@@ -14,7 +14,7 @@ export const workflowRoutes = [
     { name: "triage", worker: "agent-triage.md", description: "Triages issues opened from outside the organisation: runs 10 checks (template, security, size, danger, duplicates, clarity, reproducibility, acceptance, cross-cutting, product scope). Loops up to 3 rounds. Passes to refine, asks the author for more, parks out-of-scope work open for a maintainer, or closes what is genuinely rejected.", defaultEnabled: true },
     { name: "apply-review", worker: "agent-apply-review.md", description: "Applies reviewer feedback to an open pull request the bot authored, then pushes the fixes to the same branch.", defaultEnabled: true },
     { 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 single issue that Refine then sizes and splits.", 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"] },
 ];
@@ -57,6 +57,7 @@ export const templateNames = [
     "app-ci-dotnet-next",
     "app-ci-node-monorepo",
     "bug-report",
+    "dependabot-merge",
     "feature-request",
     "github-release",
     "opencode.ci.json",
@@ -71,10 +72,11 @@ export const catalogTemplates = [
     { name: "app-ci-dotnet-next", file: "app-ci-dotnet-next.yml", description: "App CI pipeline for a .NET + Next.js monorepo: build, test, and lint on PRs and schedule." },
     { name: "app-ci-node-monorepo", file: "app-ci-node-monorepo.yml", description: "App CI pipeline for a Node monorepo: build, test, and lint on PRs and schedule." },
     { name: "bug-report", file: "bug_report.yml", description: "Bug report issue template: what happened, repro steps, expected behavior, acceptance criteria, environment, logs.", target: ".github/ISSUE_TEMPLATE/bug_report.yml" },
+    { name: "dependabot-merge", file: ".github/workflows/dependabot-merge.yml", directory: "dependabot-merge", bundle: true, actions: ["merge-dependabot"], description: "Dependabot auto-merge for a repository without the work router: every six hours, squash-merges the Dependabot pull requests whose checks are all green and asks Dependabot to rebase the stale ones. Deterministic, no model, never runs pull request code. Works with GITHUB_TOKEN; the Platform App token is used when its secrets exist. The router does the same in its maintenance run." },
     { name: "feature-request", file: "feature_request.yml", description: "Feature request issue template scoped to small, well-scoped improvements (Small/Medium only; large work belongs in a planning issue).", target: ".github/ISSUE_TEMPLATE/feature_request.yml" },
     { name: "github-release", file: "github-release.yml", description: "Publishes or updates a GitHub Release with generated notes whenever a v* tag is pushed." },
     { name: "opencode.ci.json", file: "opencode.ci.json", description: "Standalone OpenCode CI config: plainconcepts provider, GLM model registration, ci-workflow-agent, and LSP defaults for consumer repositories." },
-    { name: "platform-template", file: "scripts/check-platform-conformance.mjs", directory: "platform-template", bundle: true, description: "Platform family template sync: a weekly workflow that runs copier update against the Kitchen-Sink template and opens a pull request per new tag, and a CI guard that keeps .platform/manifest paths unchanged outside a sync. Does nothing without .copier-answers.yml." },
+    { name: "platform-template", file: "scripts/check-platform-conformance.mjs", directory: "platform-template", bundle: true, description: "Template sync driven by the platform contract (.platform/contract.yml): a weekly workflow that runs its sync.update command and opens or updates one pull request, and a CI guard that keeps its owned paths equal to the template outside a sync. Does nothing without a contract." },
     { name: "quality-gates", file: "scripts/check-coverage.mjs", directory: "quality-gates", bundle: true, description: "Platform family quality gates: coverage, complexity, duplication and mutation gates, the Engineering Excellence facets, the Semgrep hygiene rules, jscpd and ZAP triage. Floors come from the app's quality.config.json; baselines stay app files." },
 ];
 /** Bundle templates: several package-managed files, refreshed by `update` where installed. */

package/loops/actions/file-audit-issues/action.yml

@@ -0,0 +1,193 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/file-audit-issues/action.yml. Update with workflows update --force; consumer edits may be overwritten.
+name: File audit issues
+description: >-
+  File an audit as a tracking report plus one issue per story. Every body is measured with refine's
+  size rule first and trimmed to fit, the stories get the work labels and link back to the report,
+  and the report lists them. Re-running it reuses what an earlier attempt already filed.
+inputs:
+  output-file:
+    description: Path to agent_output.json.
+    required: true
+  token:
+    description: GitHub token with issues:write. An App token, so the story labels reach the router.
+    required: true
+  report-labels:
+    description: Labels for the report, one per line. Never a work label.
+    required: false
+    default: |-
+      audit
+      bug
+  story-labels:
+    description: Labels for each story, one per line. The work label goes last.
+    required: false
+    default: |-
+      bug
+      refine
+  max-body-chars:
+    description: Largest body any filed issue may have, measured as refine measures it.
+    required: true
+  max-work-units:
+    description: Most bullet lines any filed issue may have, measured as refine measures it.
+    required: true
+  max-stories:
+    description: Most stories filed from one audit.
+    required: false
+    default: '3'
+  run-url:
+    description: This run, cited in a body that had to be trimmed.
+    required: false
+    default: ''
+  report-title:
+    description: Pattern, case-insensitive, of the report's title. Every other issue the agent filed is a story.
+    required: false
+    default: '^audit\b'
+outputs:
+  report-number:
+    description: The report's issue number, or empty when the agent filed nothing.
+    value: ${{ steps.file.outputs.report-number }}
+  story-numbers:
+    description: Space-separated numbers of the stories filed or reused.
+    value: ${{ steps.file.outputs.story-numbers }}
+runs:
+  using: composite
+  steps:
+    - name: File the report and its stories
+      id: file
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        AGENT_OUTPUT_LIB: ${{ github.action_path }}/../agent-output.cjs
+        ISSUE_SIZE_LIB: ${{ github.action_path }}/../issue-size.cjs
+        AUDIT_ISSUES_LIB: ${{ github.action_path }}/audit-issues.cjs
+        OUTPUT_FILE: ${{ inputs.output-file }}
+        REPORT_LABELS: ${{ inputs.report-labels }}
+        STORY_LABELS: ${{ inputs.story-labels }}
+        MAX_BODY_CHARS: ${{ inputs.max-body-chars }}
+        MAX_WORK_UNITS: ${{ inputs.max-work-units }}
+        MAX_STORIES: ${{ inputs.max-stories }}
+        RUN_URL: ${{ inputs.run-url }}
+        REPORT_TITLE: ${{ inputs.report-title }}
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          const { readAgentItems } = require(process.env.AGENT_OUTPUT_LIB);
+          const { measureIssue, sizeVerdict } = require(process.env.ISSUE_SIZE_LIB);
+          const audit = require(process.env.AUDIT_ISSUES_LIB);
+
+          const list = (value) => String(value ?? '').split(/\r?\n|,/).map((label) => label.trim()).filter(Boolean);
+          const reportLabels = list(process.env.REPORT_LABELS);
+          const storyLabels = list(process.env.STORY_LABELS);
+          const limits = { maxBodyChars: Number(process.env.MAX_BODY_CHARS), maxWorkUnits: Number(process.env.MAX_WORK_UNITS) };
+          if (!(limits.maxBodyChars > 0 && limits.maxWorkUnits > 0)) {
+            core.setFailed(`Invalid size limits: ${JSON.stringify(limits)}`);
+            return;
+          }
+
+          const plan = audit.planAuditIssues(readAgentItems(process.env.OUTPUT_FILE, 'create_issue'), {
+            limits,
+            maxStories: Number(process.env.MAX_STORIES) || 3,
+            runUrl: process.env.RUN_URL,
+            reportPattern: new RegExp(process.env.REPORT_TITLE || '^audit\\b', 'i'),
+          });
+          if (!plan) {
+            core.info('The agent filed no issue.');
+            core.setOutput('report-number', '');
+            core.setOutput('story-numbers', '');
+            return;
+          }
+
+          // The pre-flight: nothing is filed unless every body, rendered with the widest issue
+          // number, passes the same rule the refine guard applies.
+          const widest = audit.PLACEHOLDER_NUMBER;
+          const checks = [
+            { title: plan.report.title, body: audit.renderReport(plan.report.body, plan.stories.map((s) => ({ number: widest, title: s.title, tracked: true }))) },
+            ...plan.stories.map((s) => ({ title: s.title, body: audit.renderStory(s.body, widest) })),
+          ];
+          for (const check of checks) {
+            const verdict = sizeVerdict(measureIssue(check.title, check.body), limits);
+            if (verdict.tooBig) {
+              core.setFailed(`"${check.title}" would be refused by refine (${verdict.reason}); nothing was filed.`);
+              return;
+            }
+          }
+
+          const open = (await github.paginate(github.rest.issues.listForRepo, { ...context.repo, state: 'open', per_page: 100 }))
+            .filter((issue) => !issue.pull_request);
+          const byTitle = new Map(open.map((issue) => [audit.titleKey(issue.title), issue]));
+          const labelNames = (issue) => issue.labels.map((label) => (typeof label === 'string' ? label : label.name));
+
+          for (const name of new Set([...reportLabels, ...storyLabels])) {
+            await github.rest.issues.createLabel({ ...context.repo, name, color: 'ededed' })
+              .catch((error) => { if (error.status !== 422) throw error; });
+          }
+
+          // A re-run finds the report it filed before: same title, carrying the report labels.
+          let report = byTitle.get(audit.titleKey(plan.report.title));
+          if (report && reportLabels.every((label) => labelNames(report).includes(label))) {
+            core.info(`Reusing the report #${report.number}.`);
+          } else {
+            ({ data: report } = await github.rest.issues.create({
+              ...context.repo,
+              title: plan.report.title,
+              body: audit.renderReport(plan.report.body, []),
+            }));
+            core.info(`Filed the report #${report.number}.`);
+          }
+          const missing = reportLabels.filter((label) => !labelNames(report).includes(label));
+          if (missing.length > 0) {
+            await github.rest.issues.addLabels({ ...context.repo, issue_number: report.number, labels: missing });
+          }
+
+          const links = [];
+          const marker = audit.reportMarker(report.number);
+          for (const story of plan.stories) {
+            const existing = byTitle.get(audit.titleKey(story.title));
+            if (existing && !(existing.body ?? '').includes(marker)) {
+              // Already tracked by an issue this audit did not file: point at it, file nothing.
+              core.info(`"${story.title}" is already tracked by #${existing.number}.`);
+              links.push({ number: existing.number, title: story.title, tracked: true });
+              continue;
+            }
+            let issue = existing;
+            if (!issue) {
+              ({ data: issue } = await github.rest.issues.create({
+                ...context.repo,
+                title: story.title,
+                body: audit.renderStory(story.body, report.number),
+              }));
+              core.info(`Filed #${issue.number}: ${story.title}${story.trimmed ? ' (trimmed)' : ''}`);
+            }
+            try {
+              await github.request('POST /repos/{owner}/{repo}/issues/{issue_number}/sub_issues', {
+                ...context.repo,
+                issue_number: report.number,
+                sub_issue_id: issue.id,
+              });
+            } catch (error) {
+              // The report's checklist below links it either way; 422 is "already a sub-issue".
+              if (error.status !== 422) core.warning(`Could not link #${issue.number} under #${report.number}: ${error.message}`);
+            }
+            // Last, so refine starts on a story whose body and link are already in place. A story an
+            // earlier attempt labelled is left alone: adding `refine` again would start refine again.
+            if (storyLabels.length > 0 && labelNames(issue).length === 0) {
+              await github.rest.issues.addLabels({ ...context.repo, issue_number: issue.number, labels: storyLabels });
+            }
+            links.push({ number: issue.number, title: story.title, tracked: false });
+          }
+
+          await github.rest.issues.update({
+            ...context.repo,
+            issue_number: report.number,
+            body: audit.renderReport(plan.report.body, links),
+          });
+
+          for (const title of plan.dropped) core.warning(`Not filed, over the ${process.env.MAX_STORIES} story limit: ${title}`);
+          core.setOutput('report-number', String(report.number));
+          core.setOutput('story-numbers', links.filter((link) => !link.tracked).map((link) => link.number).join(' '));
+          await core.summary
+            .addHeading('Audit filed', 2)
+            .addList([
+              `Report #${report.number}${plan.report.trimmed ? ' (trimmed to fit)' : ''}`,
+              ...links.map((link) => `#${link.number} ${link.title}${link.tracked ? ' (already tracked)' : ''}`),
+              ...plan.dropped.map((title) => `Not filed: ${title}`),
+            ])
+            .write();

package/loops/actions/file-audit-issues/audit-issues.cjs

@@ -0,0 +1,245 @@
+// Managed by @plainconceptsplatform/workflows. Source: loops/actions/file-audit-issues/audit-issues.cjs. Update with `workflows update --force`; consumer edits may be overwritten.
+'use strict';
+
+// What the audit files, decided apart from the API calls so it can be tested on its own. Pure: no
+// network, no clock. The audit used to file one issue holding every finding and three stories,
+// labelled `refine`; refine's size gate refused every one. Now the report is a tracking issue that
+// refine never sees, each story is its own issue, and every body is measured with refine's own
+// rule before anything is filed: a body over the limits is trimmed here, never filed to be refused.
+
+const { measureIssue, sizeVerdict } = require('../issue-size.cjs');
+
+// Wide enough for any issue number, so a body measured with it only shrinks once the real one is in.
+const PLACEHOLDER_NUMBER = 9999999;
+const MAX_TITLE = 200;
+const STORY_HEADING = /^(#{1,6})\s+(.*\S)\s*$/;
+// The story section of the old single-issue shape: "## Top 3 — To Implement", "## Section 2 ...".
+const STORY_SECTION = /^(#{1,6})\s+(?:.*\bto implement\b|section 2\b)/i;
+const FENCE = /^\s*(```|~~~)/;
+
+const bytes = (text) => Buffer.byteLength(text, 'utf8');
+const units = (text) => measureIssue('', text).units;
+const titleKey = (title) => String(title ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+const cleanTitle = (title) => {
+  const flat = String(title ?? '').replace(/\s+/g, ' ').trim();
+  return flat.length > MAX_TITLE ? `${flat.slice(0, MAX_TITLE - 1)}…` : flat;
+};
+
+function reportMarker(number) {
+  return `<!-- audit-report: ${number} -->`;
+}
+
+function renderStory(body, reportNumber) {
+  return `${body.replace(/\s+$/, '')}\n\nFound by the audit report #${reportNumber}.\n${reportMarker(reportNumber)}`;
+}
+
+function renderReport(body, links) {
+  const trimmed = body.replace(/\s+$/, '');
+  if (links.length === 0) return trimmed;
+  const lines = links.map((link) => `- [ ] #${link.number} ${link.title}${link.tracked ? ' (already tracked)' : ''}`);
+  return `${trimmed}\n\n## To implement\n\n${lines.join('\n')}`;
+}
+
+// The longest prefix of `text`, whole lines, that fits the budget. An open code fence is closed, so
+// a cut never turns the rest of the issue into code. A first line too long on its own is cut short.
+function trimLines(text, budget) {
+  const lines = text.split('\n');
+  const kept = [];
+  let inFence = false;
+  for (const line of lines) {
+    const opensOrCloses = FENCE.test(line);
+    const nextInFence = opensOrCloses ? !inFence : inFence;
+    const candidate = [...kept, line, ...(nextInFence ? ['```'] : [])].join('\n');
+    if (bytes(candidate) > budget.bytes || units(candidate) > budget.units) {
+      // A bullet cut short is still a bullet, so it is only kept while a unit is left for it.
+      if (kept.length === 0 && units(line) <= budget.units) {
+        const chars = [...line];
+        while (chars.length > 0 && bytes(`${chars.join('')}…`) > budget.bytes) chars.pop();
+        if (chars.length > 0) kept.push(`${chars.join('')}…`);
+      }
+      if (inFence) kept.push('```');
+      return { text: kept.join('\n'), trimmed: true };
+    }
+    kept.push(line);
+    inFence = nextInFence;
+  }
+  return { text: kept.join('\n'), trimmed: false };
+}
+
+function trimNote(runUrl) {
+  return runUrl
+    ? `_Trimmed to fit refine's size limits. The full text is in the audit run: ${runUrl}_`
+    : "_Trimmed to fit refine's size limits._";
+}
+
+// Fits `body` so that title + body + suffix passes the limits, trimming from the end.
+function fitBody(title, body, suffix, limits, runUrl) {
+  const fits = (text) => !sizeVerdict(measureIssue(title, `${text}${suffix}`), limits).tooBig;
+  if (fits(body)) return { body, trimmed: false };
+  const note = `\n\n${trimNote(runUrl)}`;
+  const overhead = measureIssue(title, `${note}${suffix}`);
+  const budget = { bytes: limits.maxBodyChars - overhead.chars - 1, units: limits.maxWorkUnits - overhead.units };
+  const { text } = trimLines(body, budget);
+  const trimmedBody = `${text}${note}`;
+  return { body: fits(trimmedBody) ? trimmedBody : trimNote(runUrl), trimmed: true };
+}
+
+// Splits markdown at headings (only those `depth` deep, when given) into [preamble, ...sections].
+function splitAtHeadings(body, depth = 0) {
+  const blocks = [];
+  let current = [];
+  let inFence = false;
+  for (const line of body.split('\n')) {
+    if (FENCE.test(line)) inFence = !inFence;
+    const heading = !inFence && STORY_HEADING.exec(line);
+    if (heading && (!depth || heading[1].length === depth) && current.length > 0) {
+      blocks.push(current.join('\n'));
+      current = [];
+    }
+    current.push(line);
+  }
+  blocks.push(current.join('\n'));
+  return blocks;
+}
+
+// The old single-issue shape carried its stories under a "To implement" heading. Lifts that section
+// out of the report and returns its subsections as stories, so a report written the old way still
+// becomes a report plus stories rather than one issue refine refuses.
+function extractStorySection(body) {
+  const lines = body.split('\n');
+  let start = -1;
+  let level = 0;
+  let inFence = false;
+  for (const [index, line] of lines.entries()) {
+    if (FENCE.test(line)) inFence = !inFence;
+    if (inFence) continue;
+    const match = STORY_SECTION.exec(line);
+    if (match) {
+      start = index;
+      level = match[1].length;
+      break;
+    }
+  }
+  if (start === -1) return { report: body, stories: [] };
+
+  let end = lines.length;
+  inFence = false;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (FENCE.test(lines[index])) inFence = !inFence;
+    const heading = !inFence && STORY_HEADING.exec(lines[index]);
+    if (heading && heading[1].length <= level) {
+      end = index;
+      break;
+    }
+  }
+
+  // Stories are the shallowest headings inside the section; deeper ones belong to a story.
+  const section = lines.slice(start + 1, end).join('\n');
+  let fenced = false;
+  const depths = section.split('\n')
+    .map((line) => ((fenced = FENCE.test(line) ? !fenced : fenced) ? null : STORY_HEADING.exec(line)))
+    .filter(Boolean)
+    .map((match) => match[1].length);
+  const depth = depths.length > 0 ? Math.min(...depths) : 0;
+  const stories = splitAtHeadings(section, depth)
+    .map((block) => {
+      const [first, ...rest] = block.split('\n');
+      const heading = STORY_HEADING.exec(first);
+      if (!heading || heading[1].length !== depth) return null;
+      const title = heading[2].replace(/^(story\s+\w+|\d+[.)])\s*[—–:-]\s*/i, '');
+      return { title, body: rest.join('\n').trim() };
+    })
+    .filter((story) => story && story.title && story.body);
+
+  const report = [...lines.slice(0, start), ...lines.slice(end)].join('\n').replace(/\s+$/, '');
+  return { report, stories };
+}
+
+// Shares a budget among blocks so short ones keep everything and long ones split what is left.
+function shareBudget(sizes, total) {
+  const shares = new Array(sizes.length).fill(0);
+  let remaining = Math.max(0, total);
+  const order = sizes.map((size, index) => ({ size, index })).sort((a, b) => a.size - b.size);
+  order.forEach(({ size, index }, position) => {
+    const fair = Math.floor(remaining / (order.length - position));
+    shares[index] = Math.min(size, fair);
+    remaining -= shares[index];
+  });
+  return shares;
+}
+
+// Fits the report by trimming every finding to a share of the budget, so all of them stay listed
+// with their heading and first lines rather than the last ones vanishing.
+function fitReport(title, body, suffix, limits, runUrl) {
+  const fits = (text) => !sizeVerdict(measureIssue(title, `${text}${suffix}`), limits).tooBig;
+  if (fits(body)) return { body, trimmed: false };
+  const note = `\n\n${trimNote(runUrl)}`;
+  const blocks = splitAtHeadings(body);
+  const overhead = measureIssue(title, `${note}${suffix}`);
+  const separators = 2 * Math.max(0, blocks.length - 1);
+  const byteShares = shareBudget(blocks.map(bytes), limits.maxBodyChars - overhead.chars - separators - 1);
+  const unitShares = shareBudget(blocks.map(units), limits.maxWorkUnits - overhead.units);
+  const compact = blocks.map((block, index) => trimLines(block, { bytes: byteShares[index], units: unitShares[index] }).text.trimEnd())
+    .filter((block) => block.length > 0)
+    .join('\n\n');
+  const trimmedBody = `${compact}${note}`;
+  if (fits(trimmedBody)) return { body: trimmedBody, trimmed: true };
+  return fitBody(title, compact, suffix, limits, runUrl);
+}
+
+// `items` are the agent's create_issue items. The report is the one whose title matches
+// `reportPattern` ("Audit: ..." by default, "Docs audit: ..." for docs-audit), or the first; the
+// others are stories. Returns bodies that pass `limits` once rendered with any issue
+// number, which is the refine guard's check run before filing instead of after.
+function planAuditIssues(items, options) {
+  const { limits, maxStories = 3, runUrl = '', reportPattern = /^audit\b/i } = options;
+  const usable = items.filter((item) => item && String(item.title ?? '').trim());
+  if (usable.length === 0) return null;
+
+  const reportIndex = Math.max(0, usable.findIndex((item) => reportPattern.test(String(item.title).trim())));
+  const reportItem = usable[reportIndex];
+  const lifted = extractStorySection(String(reportItem.body ?? ''));
+  const separate = usable.filter((_, index) => index !== reportIndex)
+    .map((item) => ({ title: item.title, body: String(item.body ?? '').trim() }));
+
+  // Separate stories win; the lifted section is only used when the agent filed the old shape.
+  const candidates = (separate.length > 0 ? separate : lifted.stories)
+    .map((story) => ({ title: cleanTitle(story.title), body: story.body }))
+    .filter((story) => story.title && story.body);
+  const seen = new Set();
+  const unique = candidates.filter((story) => {
+    const key = titleKey(story.title);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  const dropped = unique.slice(maxStories).map((story) => story.title);
+
+  const stories = unique.slice(0, maxStories).map((story) => {
+    const suffix = renderStory('', PLACEHOLDER_NUMBER);
+    const fitted = fitBody(story.title, story.body, suffix, limits, runUrl);
+    return { title: story.title, body: fitted.body, trimmed: fitted.trimmed };
+  });
+
+  const reportTitle = cleanTitle(reportItem.title);
+  const links = stories.map((story) => ({ number: PLACEHOLDER_NUMBER, title: story.title, tracked: true }));
+  const suffix = renderReport('', links);
+  const fitted = fitReport(reportTitle, lifted.report.trim(), suffix, limits, runUrl);
+
+  return {
+    report: { title: reportTitle, body: fitted.body, trimmed: fitted.trimmed, lifted: lifted.stories.length },
+    stories,
+    dropped,
+  };
+}
+
+module.exports = {
+  PLACEHOLDER_NUMBER,
+  extractStorySection,
+  planAuditIssues,
+  renderReport,
+  renderStory,
+  reportMarker,
+  titleKey,
+  trimLines,
+};

package/loops/actions/issue-size.cjs

@@ -0,0 +1,36 @@
+// Managed by @plainconceptsplatform/workflows. Source: loops/actions/issue-size.cjs. Update with `workflows update --force`; consumer edits may be overwritten.
+'use strict';
+
+// Refine's size gate, as one rule both sides read: the refine guard measures an issue with it,
+// and the audit measures every issue it files with it before filing. While the audit had no way to
+// ask, every report it filed from 2026-09-21 on was over the gate and was refused.
+//
+// The numbers match what the guard's shell counted: `wc -c` (UTF-8 bytes) of the title, a blank
+// line and the body with trailing newlines dropped, and one work unit per `-` or `*` bullet line.
+
+const BULLET = /^[ \t\r\v\f]*[-*] /;
+
+function issueText(title, body) {
+  return `${title ?? ''}\n\n${body ?? ''}`.replace(/\n+$/, '');
+}
+
+function measureIssue(title, body) {
+  const text = issueText(title, body);
+  return {
+    chars: Buffer.byteLength(text, 'utf8'),
+    units: text.split('\n').filter((line) => BULLET.test(line)).length,
+  };
+}
+
+function sizeVerdict(size, limits) {
+  const reasons = [];
+  if (size.chars > limits.maxBodyChars) reasons.push(`body ${size.chars} chars > ${limits.maxBodyChars}`);
+  if (size.units > limits.maxWorkUnits) reasons.push(`work units ${size.units} > ${limits.maxWorkUnits}`);
+  return { tooBig: reasons.length > 0, reason: reasons.join('; ') };
+}
+
+function fitsLimits(title, body, limits) {
+  return !sizeVerdict(measureIssue(title, body), limits).tooBig;
+}
+
+module.exports = { BULLET, measureIssue, sizeVerdict, fitsLimits };