@plainconceptsplatform/workflows 1.10.0 → 1.11.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`, and `opencode.ci.json`. CI templates are stack-specific copies, not a combined template. `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 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.
 
 `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/catalog-installation.js

@@ -10,6 +10,7 @@ import { processRoutes, excludedWorkerFiles } from "./route-processing.js";
 import { generateOpencodeCi, generateOpencodeConfig, generateStackDefaults, injectStackEnv, shippedVerifyDefaults } from "./stack-defaults.js";
 import { mergeRouter, mergeWorker } from "./worker-env.js";
 import { fetchBaseline, hasOwnershipHeader, installedVersion, packageVersion, stampVersion } from "./package-baseline.js";
+import { installBundle, isBundleTemplate } from "./template-bundles.js";
 const execFileAsync = promisify(execFile);
 const sourceMappings = [
     ["actions", ".github/actions"],
@@ -286,6 +287,10 @@ const templateCompanions = {
 };
 export async function installTemplate(repositoryPath, template, options = {}) {
     const sourcePath = options.sourcePath ?? catalogSourcePath();
+    if (isBundleTemplate(template)) {
+        const bundle = await installBundle(repositoryPath, template, sourcePath, { force: options.force });
+        return { installed: bundle.installed, conflicts: [] };
+    }
     const meta = catalogTemplateMeta(template);
     const source = join(sourcePath, "templates", meta.directory, meta.file);
     const target = meta.target;

package/dist/catalog-listing.js

@@ -1,5 +1,7 @@
 import { access, constants } from "node:fs/promises";
 import { join } from "node:path";
+import { catalogSourcePath } from "./catalog-installation.js";
+import { installedBundles } from "./template-bundles.js";
 import { catalogTemplates, workflowRoutes } from "./workflow-catalog.js";
 export async function listCatalog(options = {}) {
     const basePath = options.installedPath ?? process.cwd();
@@ -10,12 +12,15 @@ export async function listCatalog(options = {}) {
         file: route.worker,
         installed: await isFileInstalled(basePath, route.worker),
     })));
+    // A bundle counts as installed by its ownership headers, not by its paths: a repository may keep
+    // its own headerless files at the same places.
+    const bundles = await installedBundles(basePath, catalogSourcePath());
     const templates = await Promise.all(catalogTemplates.map(async (template) => ({
         kind: "template",
         name: template.name,
         description: template.description,
         file: template.file,
-        installed: await isFileInstalled(basePath, template.file, template.target),
+        installed: template.bundle === true ? bundles.includes(template.name) : await isFileInstalled(basePath, template.file, template.target),
     })));
     return [...routes, ...templates];
 }

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { inspectRepository, parseVisibility, resolveVisibility } from "./repository-inspection.js";
-import { installCatalog, installedRoutes, installTemplate, isTemplateName, removeRouteFiles } from "./catalog-installation.js";
+import { catalogSourcePath, 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";
@@ -48,7 +49,9 @@ What an update does to a package-managed file:
   follows the package when its default changes. The agent runner pool and the engine gateway URL
   are kept as well. Everything else in the file is the package's.
   A file whose ownership header was removed is yours and is left alone unless --force is passed.
-  Templates are yours after installation and are replaced only with --force.
+  Single-file templates are yours after installation and are replaced only with --force.
+  Bundle templates (quality-gates, platform-template) stay package-managed like the catalog:
+  add --template installs one, and update refreshes it only where its files carry the header.
 
 Options:
   --dry-run                                   Print what add or update would change, write nothing.
@@ -118,15 +121,25 @@ export async function run(arguments_, repositoryPath = process.cwd()) {
         const allInstalled = [];
         let catalog;
         const templatesPlanned = [];
+        const bundles = [];
+        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.
+        // 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));
             catalog = await installCatalog(repositoryPath, { force, dryRun, selectedRoutes, inspection, baseline });
             allConflicts.push(...catalog.conflicts);
             allInstalled.push(...catalog.installed);
+            for (const name of await installedBundles(repositoryPath, sourcePath)) {
+                if (name !== template)
+                    bundles.push(await installBundle(repositoryPath, name, sourcePath, { force, dryRun }));
+            }
+        }
+        if (template !== undefined && isBundleTemplate(template)) {
+            bundles.push(await installBundle(repositoryPath, template, sourcePath, { force, dryRun }));
         }
-        if (template !== undefined) {
+        else if (template !== undefined) {
             if (dryRun) {
                 templatesPlanned.push(template);
             }
@@ -142,11 +155,14 @@ export async function run(arguments_, repositoryPath = process.cwd()) {
         }
         for (const warning of catalog?.warnings ?? [])
             console.error(`warning: ${warning}`);
+        for (const bundle of bundles)
+            allInstalled.push(...bundle.installed);
         console.log(JSON.stringify({
             command,
             dryRun,
             ...(catalog === undefined ? {} : summarize(catalog)),
             ...(templatesPlanned.length > 0 ? { templatesPlanned } : {}),
+            ...(bundles.length > 0 ? { templates: bundles.map(summarizeBundle) } : {}),
             installed: allInstalled.sort(),
             conflicts: allConflicts,
         }, null, 2));
@@ -183,6 +199,13 @@ function summarize(result) {
         ...(result.warnings.length > 0 ? { warnings: result.warnings } : {}),
     };
 }
+function summarizeBundle(result) {
+    return {
+        template: result.template,
+        changes: result.changes.filter((change) => change.status !== "unchanged"),
+        unchanged: result.changes.filter((change) => change.status === "unchanged").length,
+    };
+}
 // A fixed baseline for every recorded version, instead of asking npm. Rolling out a version that
 // is not published yet leaves the merge two-way, which keeps every consumer value, including the
 // package defaults a consumer never chose and would rather have replaced.

package/dist/template-bundles.d.ts

@@ -0,0 +1,21 @@
+import type { FileChange } from "./catalog-installation.js";
+import { type TemplateName } from "./workflow-catalog.js";
+export interface BundleInstallOptions {
+    /** Also overwrite files whose ownership header was removed. */
+    readonly force?: boolean;
+    /** Compute the plan and write nothing. */
+    readonly dryRun?: boolean;
+    readonly sourcePath?: string;
+    /** The version stamped into headers. Defaults to this package's. */
+    readonly packageVersion?: string;
+}
+export interface BundleInstallResult {
+    readonly template: TemplateName;
+    /** Every target of the bundle, whether it changed or not. */
+    readonly installed: readonly string[];
+    readonly changes: readonly FileChange[];
+}
+export declare function isBundleTemplate(template: TemplateName): boolean;
+/** The bundles whose files carry our ownership header in this repository. */
+export declare function installedBundles(repositoryPath: string, sourcePath: string): Promise<TemplateName[]>;
+export declare function installBundle(repositoryPath: string, template: TemplateName, sourcePath: string, options?: BundleInstallOptions): Promise<BundleInstallResult>;

package/dist/template-bundles.js

@@ -0,0 +1,108 @@
+// A bundle template stays package-managed after installation, under the catalog's header rules. It
+// counts as installed only where one of its files carries our header, so `update` never reaches a
+// repository that keeps its own headerless copies of the same paths.
+import { access, chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { hasOwnershipHeader, installedVersion, packageVersion, stampVersion } from "./package-baseline.js";
+import { bundleTemplateNames, catalogTemplates } from "./workflow-catalog.js";
+const CONSUMER_OWNED = "consumer-owned: the ownership header was removed; pass --force to reclaim it";
+const carriesHeader = (target) => /\.(ya?ml|md|sh|mjs|cjs|tsv)$/.test(target);
+const normalizeEol = (text) => text.replaceAll("\r\n", "\n");
+export function isBundleTemplate(template) {
+    return bundleTemplateNames.includes(template);
+}
+/** The bundles whose files carry our ownership header in this repository. */
+export async function installedBundles(repositoryPath, sourcePath) {
+    const installed = [];
+    for (const template of bundleTemplateNames) {
+        for (const target of await bundleTargets(sourcePath, template)) {
+            if (!carriesHeader(target))
+                continue;
+            const current = await readOptional(join(repositoryPath, target));
+            if (current !== undefined && hasOwnershipHeader(current)) {
+                installed.push(template);
+                break;
+            }
+        }
+    }
+    return installed;
+}
+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 changes = [];
+    const writes = [];
+    for (const target of targets) {
+        const current = await readOptional(join(repositoryPath, target));
+        const text = stampVersion(normalizeEol(await readFile(join(root, target), "utf8")), version);
+        const recorded = current === undefined ? undefined : installedVersion(current);
+        const base = recorded === undefined ? { target } : { target, installedVersion: recorded };
+        if (current === text) {
+            changes.push({ ...base, status: "unchanged" });
+        }
+        else if (current !== undefined && !options.force && await consumerOwned(repositoryPath, target, current, targets)) {
+            changes.push({ target, status: "skipped", reason: CONSUMER_OWNED });
+        }
+        else if (current === undefined && documentsSkippedJson(target, changes)) {
+            // The JSON this note documents stays the consumer's, so the note would claim a file we do not own.
+            changes.push({ target, status: "skipped", reason: `documents the consumer-owned ${target.slice(0, -".md".length)}` });
+        }
+        else {
+            changes.push({ ...base, status: current === undefined ? "added" : "updated" });
+            writes.push({ target, content: text });
+        }
+    }
+    if (!options.dryRun) {
+        for (const { target, content } of writes) {
+            const destination = join(repositoryPath, target);
+            await mkdir(dirname(destination), { recursive: true });
+            await writeFile(destination, content, "utf8");
+            // A script a workflow runs by its path needs the executable bit, which a plain write never sets.
+            if (content.startsWith("#!"))
+                await chmod(destination, 0o755);
+        }
+    }
+    return { template, installed: targets, changes };
+}
+// A JSON file's header lives in its companion `<file>.md`; without that note the JSON is the consumer's.
+async function consumerOwned(repositoryPath, target, current, targets) {
+    if (carriesHeader(target))
+        return !hasOwnershipHeader(current);
+    const companion = `${target}.md`;
+    if (!targets.includes(companion))
+        return false;
+    const note = await readOptional(join(repositoryPath, companion));
+    return note === undefined || !hasOwnershipHeader(note);
+}
+// Targets are sorted, so a JSON file is always decided before the `<file>.md` that documents it.
+function documentsSkippedJson(target, changes) {
+    if (!target.endsWith(".json.md"))
+        return false;
+    const json = target.slice(0, -".md".length);
+    return changes.some((change) => change.target === json && change.status === "skipped");
+}
+function bundleRoot(sourcePath, template) {
+    const entry = catalogTemplates.find((item) => item.name === template);
+    if (entry?.bundle !== true || entry.directory === undefined)
+        throw new Error(`${template} is not a bundle template`);
+    return join(sourcePath, "templates", entry.directory);
+}
+async function bundleTargets(sourcePath, template) {
+    const root = bundleRoot(sourcePath, template);
+    const entries = await readdir(root, { recursive: true, withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => relative(root, join(entry.parentPath, entry.name)).replaceAll("\\", "/"))
+        .sort();
+}
+async function readOptional(path) {
+    try {
+        await access(path, constants.F_OK);
+    }
+    catch {
+        return undefined;
+    }
+    return normalizeEol(await readFile(path, "utf8"));
+}

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"];
+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 type TemplateName = (typeof templateNames)[number];
 export interface CatalogTemplate {
     readonly name: TemplateName;
@@ -28,5 +28,9 @@ export interface CatalogTemplate {
     readonly target?: string;
     /** Subdirectory of `templates/` holding the file. Defaults to "agentics". */
     readonly directory?: string;
+    /** Several files under `templates/<directory>/`, package-managed and refreshed by `update` where installed. */
+    readonly bundle?: boolean;
 }
 export declare const catalogTemplates: readonly CatalogTemplate[];
+/** Bundle templates: several package-managed files, refreshed by `update` where installed. */
+export declare const bundleTemplateNames: readonly TemplateName[];

package/dist/workflow-catalog.js

@@ -60,6 +60,8 @@ export const templateNames = [
     "feature-request",
     "github-release",
     "opencode.ci.json",
+    "platform-template",
+    "quality-gates",
 ];
 export const catalogTemplates = [
     { name: "agentics-app-errors", file: "agentics-app-errors.yml", description: "Daily application error report: asks Application Insights what the deployed app threw, groups it, and files one issue per distinct problem HERE, labelled bug + refine so the belt picks it up. Deterministic, no model; the report never leaves this repository, and a leak scanner withholds anything carrying an identifier." },
@@ -72,4 +74,10 @@ export const catalogTemplates = [
     { 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: "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. */
+export const bundleTemplateNames = catalogTemplates
+    .filter((template) => template.bundle === true)
+    .map((template) => template.name);

package/loops/actions/report-workflow-errors/action.yml

@@ -29,6 +29,12 @@ inputs:
       occurrence is a blip; an issue that is already open is always appended to.
     required: false
     default: '2'
+  min-occurrences-unknown:
+    description: >-
+      The same, for a failure the catalogue could not classify. With no diagnosis behind it, a
+      cause has to repeat more before it is worth a person's time.
+    required: false
+    default: '3'
   max-findings:
     description: The most issues one run opens, the most frequent first. The rest stay in the job summary.
     required: false
@@ -58,6 +64,7 @@ runs:
         UPSTREAM_REPO: ${{ inputs.upstream-repo }}
         LOOKBACK_HOURS: ${{ inputs.lookback-hours }}
         MIN_OCCURRENCES: ${{ inputs.min-occurrences }}
+        MIN_UNKNOWN: ${{ inputs.min-occurrences-unknown }}
         MAX_FINDINGS: ${{ inputs.max-findings }}
         QUIET_DAYS: ${{ inputs.quiet-days }}
         POLICY_PATH: ${{ github.action_path }}/report-policy.cjs
@@ -118,7 +125,7 @@ runs:
           // line carries repository paths, branch names and issue titles.
           const CATALOGUE = [
             { id: 'runner-never-assigned', test: /waiting for a runner|no runner matching|requested labels/i, note: 'A job waited for a self-hosted runner that never arrived.' },
-            { id: 'runner-lost-mid-job', test: /lost communication with the server|runner has received a shutdown signal|The self-hosted runner:.*lost/i, note: 'The runner disappeared while a job was running.' },
+            { id: 'runner-lost-mid-job', test: /lost communication with the server|runner has received a shutdown signal|The self-hosted runner:.*lost|exit code 143/i, note: 'The runner disappeared while a job was running.' },
             { id: 'job-cancelled-by-timeout', test: /The job running on runner .* has exceeded the maximum execution time|timeout-minutes/i, note: 'A job hit its timeout instead of finishing.' },
             { id: 'out-of-disk', test: /no space left on device|You are running out of disk space/i, note: 'The runner ran out of disk.' },
             { id: 'out-of-memory', test: /JavaScript heap out of memory|Killed\s+process|OOMKilled/i, note: 'A step was killed for memory.' },
@@ -187,7 +194,7 @@ runs:
           // Things that happened and are worth a number in the job summary, but that nobody can
           // fix by editing a workflow, so they never open an issue: a cancelled job with no step
           // that failed, a log that could not be read, and the fleet's own transient causes.
-          const quiet = { cancelledNoStep: 0, unreadable: 0, infra: new Map() };
+          const quiet = { cancelledNoStep: 0, unreadable: 0, retried: 0, reviewChecks: 0, infra: new Map() };
           let queueWaitTotal = 0;
           let queueWaitCount = 0;
           let queueWaitWorst = 0;
@@ -213,6 +220,9 @@ runs:
             if (!['failure', 'cancelled', 'timed_out', 'startup_failure'].includes(run.conclusion)) continue;
             ownedFailures += 1;
 
+            // A lint check failing on a pull request has done its job on somebody's change.
+            if (policy.isReviewCheck({ workflow: file, event: run.event })) { quiet.reviewChecks += 1; continue; }
+
             let jobs = [];
             try {
               jobs = await github.paginate(github.rest.actions.listJobsForWorkflowRunAttempt, {
@@ -220,6 +230,10 @@ runs:
               });
             } catch { continue; }
 
+            // The worker already caught this one and sent the work back through the router; the
+            // attempt that parks does not retry, so a failure no retry got past is still read.
+            if (policy.wasRetried(jobs)) { quiet.retried += 1; continue; }
+
             for (const job of jobs) {
               if (job.started_at && job.created_at) {
                 const wait = (new Date(job.started_at) - new Date(job.created_at)) / 1000;
@@ -251,20 +265,24 @@ runs:
                 annotationText = notes.map((note) => note.message ?? '').join('\n');
               } catch { /* annotations are an extra; the log can still classify */ }
 
-              let patternId = 'unrecognised';
+              // A step whose name already says what failed is not read further: a missing secret
+              // is the repository's to set, whatever the log says around it.
+              let patternId = policy.causeFromStep(step?.name) ?? 'unrecognised';
               let logRead = true;
-              try {
-                const { data: log } = await github.rest.actions.downloadJobLogsForWorkflowRun({
-                  ...context.repo, job_id: job.id,
-                });
-                const text = typeof log === 'string' ? log : Buffer.from(log).toString('utf8');
-                // The tail is where the failure is, and reading less of the log is less to get
-                // wrong. Only the matched entry's id crosses into the report.
-                const tail = `${annotationText}\n${text.slice(-20000)}`;
-                patternId = CATALOGUE.find((entry) => entry.test.test(tail))?.id ?? 'unrecognised';
-              } catch {
-                logRead = false;
-                patternId = CATALOGUE.find((entry) => entry.test.test(annotationText))?.id ?? 'log-unavailable';
+              if (patternId === 'unrecognised') {
+                try {
+                  const { data: log } = await github.rest.actions.downloadJobLogsForWorkflowRun({
+                    ...context.repo, job_id: job.id,
+                  });
+                  const text = typeof log === 'string' ? log : Buffer.from(log).toString('utf8');
+                  // The tail is where the failure is, and reading less of the log is less to get
+                  // wrong. Only the matched entry's id crosses into the report.
+                  const tail = `${annotationText}\n${text.slice(-20000)}`;
+                  patternId = CATALOGUE.find((entry) => entry.test.test(tail))?.id ?? 'unrecognised';
+                } catch {
+                  logRead = false;
+                  patternId = CATALOGUE.find((entry) => entry.test.test(annotationText))?.id ?? 'log-unavailable';
+                }
               }
 
               // A log nobody could read says nothing, so it is counted and not filed.
@@ -303,7 +321,8 @@ runs:
           }
 
           const catalogueNote = (id) => CATALOGUE.find((entry) => entry.id === id)?.note
-            ?? (id === 'log-unavailable' ? 'The job log could not be read, so the failure could not be classified.'
+            ?? (id === 'missing-secret' ? 'A workflow stopped at a check for a secret this repository has not set.'
+              : id === 'log-unavailable' ? 'The job log could not be read, so the failure could not be classified.'
               : 'The log matched no known failure shape. Worth adding one to the catalogue.');
 
           const ranked = [...findings.values()].sort((a, b) => b.count - a.count);
@@ -313,6 +332,7 @@ runs:
           // person's time, and a bad night opens a handful of issues rather than forty.
           const selection = policy.select(ranked, {
             minOccurrences: Number(process.env.MIN_OCCURRENCES),
+            minUnknown: Number(process.env.MIN_UNKNOWN),
             maxFindings: Number(process.env.MAX_FINDINGS),
           });
 
@@ -385,6 +405,8 @@ runs:
               `Distinct failure signatures: ${ranked.length}`,
               `Filed or appended: ${selection.file.length}; held back: ${selection.held.length}`,
               `Cancelled jobs with no failing step, not reported: ${quiet.cancelledNoStep}`,
+              `Runs whose failure the worker retried through the router, not reported: ${quiet.retried}`,
+              `Checks that failed on a pull request, not reported: ${quiet.reviewChecks}`,
               `Jobs whose log could not be read, not reported: ${quiet.unreadable}`,
               `Infrastructure causes, counted and not reported: ${[...quiet.infra].map(([id, n]) => `${id} ${n}`).join(', ') || 'none'}`,
               queueWaitCount > 0
@@ -397,6 +419,12 @@ runs:
             ])
             .write();
 
+          // The repository's own configuration is said here, to the people who can change it, and
+          // nowhere else. The step name is the package's (or gh-aw's) own words.
+          for (const { finding } of selection.held.filter(({ finding }) => finding.severity === 'consumer')) {
+            core.warning(`${finding.count} job(s) of ${finding.workflow} stopped at "${finding.step}": set the secret it checks for, or the work it guards never runs.`);
+          }
+
           if (ranked.length === 0) {
             core.info('No failures in the window for any workflow this package ships.');
             core.setOutput('filed', '');
@@ -427,6 +455,18 @@ runs:
           const upstream = getOctokit(upstreamToken);
           const filed = [];
 
+          // The latest release, to tell a failure a release may already have fixed from one that
+          // is still live. Best effort: a token that cannot read tags files as before.
+          let latestRelease = '';
+          try {
+            const { data: tags } = await upstream.rest.repos.listTags({
+              owner: upstreamOwner, repo: upstreamName, per_page: 100,
+            });
+            latestRelease = policy.latestVersion(tags.map((tag) => tag.name));
+          } catch (error) {
+            core.info(`could not read the upstream tags: HTTP ${error.status ?? '?'}`);
+          }
+
           for (const { finding, title, body } of reports) {
             const marker = body.split('\n')[0];
             // One issue per signature, updated rather than repeated. Searching by the marker
@@ -450,6 +490,13 @@ runs:
               core.warning(`could not search upstream for an existing report: HTTP ${error.status ?? '?'}`);
             }
 
+            // An install a minor or more behind does not open a new issue: update it first. It
+            // still appends to one that is open, because then the bug is live on newer versions too.
+            if (!existing && policy.isOutdated(packageVersion, latestRelease)) {
+              core.info(`left alone, ${packageVersion} is behind ${latestRelease}; update first: ${title}`);
+              continue;
+            }
+
             if (dryRun) {
               core.info(`[dry-run] would ${existing ? `append to #${existing.number}` : 'open an issue'}: ${title}`);
               continue;

package/loops/actions/report-workflow-errors/report-policy.cjs

@@ -10,6 +10,11 @@
 // a runner shut down under a job, 47% re-filed a signature seen before, every one was closed as
 // not planned and none had a comment. What follows is the filter that would have kept about a
 // hundred of them out of that pile and left the rest as a count in the job summary.
+//
+// The 11 that still got through in the week to 2026-11-03 were the next layer: 39 jobs a day failing
+// gh-aw's check for an engine secret the repository never set, agent failures the worker had
+// already sent back through the router and recovered, a shellcheck step failing on a pull request
+// it was right to fail, and installs several minors behind reporting what a release had fixed.
 
 'use strict';
 
@@ -27,6 +32,13 @@ const INFRA = new Set([
   'out-of-memory',
 ]);
 
+// Causes that belong to the repository that installed the package: a secret it never set. They are
+// warned about in that repository's own job summary, where the person who can set it will look,
+// and never filed upstream, where nobody can.
+const CONSUMER = new Set([
+  'missing-secret',
+]);
+
 // Causes that are a defect in something this package ships.
 const PACKAGE_BUG = new Set([
   'jq-error',
@@ -39,13 +51,75 @@ const PACKAGE_BUG = new Set([
   'gh-api-409-conflict',
 ]);
 
-/** infra, package-bug, or unknown (a cause nobody classified yet, worth a look when it repeats). */
+/** infra, consumer, package-bug, or unknown (a cause nobody classified yet, worth a look when it repeats). */
 function severityOf(patternId) {
   if (INFRA.has(patternId)) return 'infra';
+  if (CONSUMER.has(patternId)) return 'consumer';
   if (PACKAGE_BUG.has(patternId)) return 'package-bug';
   return 'unknown';
 }
 
+/**
+ * Some steps say what failed by their name alone, and their log says it in words the catalogue
+ * cannot safely match: gh-aw's secret check names the variable, and a pattern for that name would
+ * put an engine name in a file that asserts it never reaches for a model. Step names are the
+ * package's own (or gh-aw's, compiled into the package's lock files), so they are safe to read.
+ */
+function causeFromStep(step) {
+  if (/^Validate .* secrets?$/i.test(step ?? '')) return 'missing-secret';
+  if (/^Check workflow lock file$/i.test(step ?? '')) return 'lock-out-of-date';
+  return null;
+}
+
+/**
+ * A worker that hits a short run, a runner shutdown or a cut-off sends the work back through the
+ * router (decide-agent-retry) and the next attempt usually lands. The failed agent job stays red in
+ * the run that retried it, and used to be filed as if nothing had caught it. A run whose retry step
+ * succeeded has had its failure answered; the attempt that finally parks does not retry, so a
+ * failure the retries never got past is still counted.
+ */
+function wasRetried(jobs) {
+  return (jobs ?? []).some((job) => (job.steps ?? []).some((step) =>
+    /^Send the (work|issue) back through the router$/.test(step.name ?? '') && step.conclusion === 'success'));
+}
+
+/**
+ * agentics-checks lints the repository's workflows and actions. On a pull request a red check is
+ * the check doing its job on somebody's change; only on the default branch, where the package's
+ * own files are what is there, can its failure be the package's.
+ */
+function isReviewCheck({ workflow, event }) {
+  return workflow === 'agentics-checks.yml' && (event === 'pull_request' || event === 'pull_request_target');
+}
+
+/**
+ * Whether the reporting install is a minor or more behind the latest release. Its failure may be
+ * one the release already fixed, so it does not open an issue; it still appends to one that is
+ * open. Patch versions are left alone: the fleet is rolled out the same day and a patch behind is
+ * the normal state for hours after every release.
+ */
+function isOutdated(reporting, latest) {
+  const parse = (v) => /^v?(\d+)\.(\d+)\./.exec(v ?? '')?.slice(1, 3).map(Number);
+  const a = parse(reporting);
+  const b = parse(latest);
+  if (!a || !b) return false;
+  return a[0] < b[0] || (a[0] === b[0] && a[1] < b[1]);
+}
+
+/**
+ * The newest release among the upstream tags. Tags, not GitHub releases or the npm dist-tag: the
+ * fleet is rolled out from tags, and both of the others have lagged them by several minors.
+ */
+function latestVersion(tags) {
+  let best = '';
+  for (const tag of tags ?? []) {
+    if (!/^v?\d+\.\d+\.\d+$/.test(tag)) continue;
+    const [a, b] = [tag, best].map((v) => v.replace(/^v/, '').split('.').map(Number));
+    if (!best || a[0] > b[0] || (a[0] === b[0] && (a[1] > b[1] || (a[1] === b[1] && a[2] > b[2])))) best = tag;
+  }
+  return best;
+}
+
 /**
  * One cause is one issue. A specific cause is the same defect whichever job of the router tripped
  * on it, so the job and the step are not part of its identity: conclude, safe_outputs and reserve
@@ -65,19 +139,26 @@ function markerKey({ workflow, step, conclusion, patternId }) {
 /**
  * Which findings become issues, and why the others do not.
  *  - infra causes are held: they are a rate, not a bug.
+ *  - consumer causes are held: the repository that has them is the one that can fix them.
  *  - a finding seen fewer than `minOccurrences` times in the window is held: once is a blip.
+ *  - an unrecognised cause needs `minUnknown`: with no diagnosis, twice in a day was mostly a
+ *    provider hiccup nobody could act on.
  *  - at most `maxFindings` are filed per run, the most frequent first, so a bad night opens a
  *    handful of issues and not forty.
  */
-function select(findings, { minOccurrences = 2, maxFindings = 5 } = {}) {
+function select(findings, { minOccurrences = 2, minUnknown = 3, maxFindings = 5 } = {}) {
   const ranked = [...findings].sort((a, b) => b.count - a.count);
   const file = [];
   const held = [];
+  const neededFor = (finding) => (finding.severity === 'unknown' ? Math.max(minOccurrences, minUnknown) : minOccurrences);
   for (const finding of ranked) {
     if (finding.severity === 'infra') {
       held.push({ finding, reason: 'infrastructure cause, counted not filed' });
-    } else if (finding.count < minOccurrences) {
-      held.push({ finding, reason: `seen ${finding.count} time(s), under the ${minOccurrences} needed to file` });
+    } else if (finding.severity === 'consumer') {
+      held.push({ finding, reason: "this repository's own configuration, warned here not filed" });
+    } else if (finding.count < neededFor(finding)) {
+      const needed = neededFor(finding);
+      held.push({ finding, reason: `seen ${finding.count} time(s), under the ${needed} needed to file` });
     } else if (file.length >= maxFindings) {
       held.push({ finding, reason: `over the ${maxFindings} filed per run` });
     } else {
@@ -107,4 +188,7 @@ function parseVersion(header) {
   return match ? match[1] : 'unknown';
 }
 
-module.exports = { INFRA, PACKAGE_BUG, severityOf, signatureOf, markerKey, select, isQuiet, parseVersion };
+module.exports = {
+  INFRA, CONSUMER, PACKAGE_BUG, severityOf, causeFromStep, wasRetried, isReviewCheck, isOutdated, latestVersion,
+  signatureOf, markerKey, select, isQuiet, parseVersion,
+};