@plainconceptsplatform/workflows 1.8.3 → 1.9.1

package/README.md

@@ -46,7 +46,7 @@ workflows add refine --template agentics-checks --force  # routes + template + m
 workflows remove audit                     # uninstall the audit worker and drop it from the router
 ```
 
-Route names: refine, implement, triage, apply-review, merge-gate, audit, release. Unknown arguments produce an error.
+Route names: refine, implement, triage, apply-review, merge-gate, audit, docs-audit, release. `docs-audit` is optional: it installs only when named. Unknown arguments produce an error.
 
 ## Update
 

package/dist/catalog-installation.js

@@ -5,7 +5,7 @@ import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { parse as parseYaml } from "yaml";
-import { catalogTemplates, mandatoryFiles, retiredWorkflowFiles, routeNames, templateNames, workflowRoutes } from "./workflow-catalog.js";
+import { catalogTemplates, defaultRouteNames, mandatoryFiles, retiredWorkflowFiles, templateNames, workflowRoutes } from "./workflow-catalog.js";
 import { processRoutes, excludedWorkerFiles } from "./route-processing.js";
 import { generateOpencodeCi, generateOpencodeConfig, generateStackDefaults, injectStackEnv, shippedVerifyDefaults } from "./stack-defaults.js";
 import { mergeRouter, mergeWorker } from "./worker-env.js";
@@ -40,7 +40,7 @@ const normalizeEol = (text) => text.replaceAll("\r\n", "\n");
 export async function installCatalog(repositoryPath, options = {}) {
     const version = options.packageVersion ?? await packageVersion();
     const sourcePath = options.sourcePath ?? catalogSourcePath();
-    const selectedRoutes = options.selectedRoutes ?? routeNames;
+    const selectedRoutes = options.selectedRoutes ?? defaultRouteNames;
     const allFiles = [...await catalogFiles(sourcePath), ...mandatoryFileSpecs(sourcePath)];
     const deduplicated = allFiles.filter((file, index) => allFiles.findIndex((f) => f.target === file.target) === index).sort((left, right) => left.target.localeCompare(right.target));
     const excluded = excludedWorkerFiles(selectedRoutes);

package/dist/route-processing.js

@@ -4,6 +4,7 @@ import { routeNames, workflowRoutes } from "./workflow-catalog.js";
 // route matrix reads the installed worker files, so neither is rewritten here.
 const routeCrons = {
     audit: "17 1 * * 1",
+    "docs-audit": "47 2 1,15 * *",
 };
 // Deterministic router jobs that exist only to serve one worker route. They leave with it, or
 // the route matrix finds a `route == 'implement'` guard in a router with no implement worker.
@@ -19,9 +20,11 @@ const routeHelperOperations = {
 };
 export function stripRouteFromRouter(yaml, route) {
     let result = yaml;
+    // By the slot comment as well as the value: a repository picks its own slot, and the shipped
+    // line carries that comment, so matching the bare default alone left the cron behind.
     const cron = routeCrons[route];
     if (cron !== undefined) {
-        result = result.replace(new RegExp(`^    - cron: "${escapeRegex(cron)}"\\n`, "gm"), "");
+        result = result.replace(new RegExp(`^    - cron: "(?:${escapeRegex(cron)}"|[^"]*" # ${escapeRegex(route)} slot.*)\\n`, "gm"), "");
     }
     for (const job of [`call-${route}`, ...(routeHelperJobs[route] ?? [])]) {
         result = removeJobBlock(result, job);

package/dist/worker-env.d.ts

@@ -32,7 +32,7 @@ export declare function mergeWorkerEnv(packageContent: string, consumerContent:
     content: string;
     report: WorkerMergeReport;
 };
-/** Copy the router's own `env:` values into the two literal lines that cannot read them. */
+/** Copy the router's own `env:` values into the literal lines that cannot read them. */
 export declare function mirrorRouterLiterals(router: string): string;
 /** The package's router with the consumer's `env:` values put back and mirrored into place. */
 export declare function mergeRouter(packageContent: string, consumerContent: string, baselineContent?: string): {

package/dist/worker-env.js

@@ -142,13 +142,14 @@ function engineEndpoint(content) {
 // now: every job, router and release included, belongs on the Azure fleet (agents-arc, runner
 // group `agentic`). The route matrix asserts it, so a repo cannot drift back without a red run. Per the standing rule for this package, anything a
 // consumer really must vary belongs in `env:` at the top of the file, not in `runs-on`.
-// GitHub evaluates no expression in a `workflow_run.workflows:` list or in a `cron:`, so the two
+// GitHub evaluates no expression in a `workflow_run.workflows:` list or in a `cron:`, so the
 // router values that are also needed there cannot be read from `env:` at those two lines. The
 // installer copies them in instead, which is what keeps the pair in step across an update; the
 // route matrix asserts the copies still agree.
 const CI_NAME_TRIGGER = /^(\s*workflows: \[")[^"]*("\]\s*)$/m;
 const AUDIT_CRON_LINE = /^(\s*- cron: ")[^"]*(" # audit slot.*)$/m;
-/** Copy the router's own `env:` values into the two literal lines that cannot read them. */
+const DOCS_AUDIT_CRON_LINE = /^(\s*- cron: ")[^"]*(" # docs-audit slot.*)$/m;
+/** Copy the router's own `env:` values into the literal lines that cannot read them. */
 export function mirrorRouterLiterals(router) {
     const values = new Map(parseYamlEnv(router).entries.map((entry) => [entry.key, unquote(entryValue(entry))]));
     const ciName = values.get("CI_WORKFLOW_NAME");
@@ -158,6 +159,9 @@ export function mirrorRouterLiterals(router) {
         result = result.replace(CI_NAME_TRIGGER, `$1${ciName}$2`);
     if (auditCron !== undefined)
         result = result.replace(AUDIT_CRON_LINE, `$1${auditCron}$2`);
+    const docsAuditCron = values.get("DOCS_AUDIT_CRON");
+    if (docsAuditCron !== undefined)
+        result = result.replace(DOCS_AUDIT_CRON_LINE, `$1${docsAuditCron}$2`);
     return result;
 }
 function unquote(value) {

package/dist/workflow-catalog.d.ts

@@ -1,4 +1,4 @@
-export declare const routeNames: readonly ["refine", "implement", "triage", "apply-review", "merge-gate", "audit", "release"];
+export declare const routeNames: readonly ["refine", "implement", "triage", "apply-review", "merge-gate", "audit", "docs-audit", "release"];
 export type RouteName = (typeof routeNames)[number];
 export interface WorkflowRoute {
     readonly name: RouteName;
@@ -9,6 +9,8 @@ export interface WorkflowRoute {
     readonly companions?: readonly string[];
 }
 export declare const workflowRoutes: readonly WorkflowRoute[];
+/** What an install with no explicit selection gets. An optional worker is added by name. */
+export declare const defaultRouteNames: readonly RouteName[];
 export declare const retiredWorkflowFiles: readonly ["agent-visual-verify.md", "agent-visual-verify.lock.yml"];
 export declare const packageOwnedTargets: readonly [".github/actions", ".github/workflows/agent-*.md", ".github/workflows/shared/platform-defaults.md", ".github/workflows/shared/opencode-ci.md", ".github/workflows/work-router.yml", ".github/workflows/evidence.yml", "scripts/compile-agent-workflows.mjs", "opencode.ci.json", "docs/diagrams.md"];
 export interface MandatoryFile {

package/dist/workflow-catalog.js

@@ -5,6 +5,7 @@ export const routeNames = [
     "apply-review",
     "merge-gate",
     "audit",
+    "docs-audit",
     "release",
 ];
 export const workflowRoutes = [
@@ -14,8 +15,13 @@ export const workflowRoutes = [
     { 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: "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"] },
 ];
+/** What an install with no explicit selection gets. An optional worker is added by name. */
+export const defaultRouteNames = workflowRoutes
+    .filter((route) => route.defaultEnabled)
+    .map((route) => route.name);
 // Workflow files the package used to ship and no longer does. `.github/workflows/` is not pruned
 // wholesale, because a missing worker there means a route the consumer left out, so a retired one
 // is named here or it sits in every consumer forever with a lock that still compiles.

package/loops/actions/audit-close/action.yml

@@ -21,12 +21,19 @@ runs:
       with:
         github-token: ${{ inputs.token }}
         script: |
-          const reports = await github.paginate(github.rest.issues.listForRepo, {
-            ...context.repo,
-            state: 'open',
-            labels: 'audit',
-            per_page: 100,
-          });
+          // A documentation audit is the same chain: a report Refine splits into children. A
+          // report carrying both labels must not be processed twice.
+          const reportsById = new Map();
+          for (const labels of ['audit', 'docs-audit']) {
+            const found = await github.paginate(github.rest.issues.listForRepo, {
+              ...context.repo,
+              state: 'open',
+              labels,
+              per_page: 100,
+            });
+            for (const report of found) reportsById.set(report.number, report);
+          }
+          const reports = [...reportsById.values()];
 
           if (reports.length === 0) {
             core.info('No open audit reports.');

package/loops/actions/classify-route/classify-route.sh

@@ -13,6 +13,7 @@ set -euo pipefail
 # fired on a cron this file does not know classifies to no route and dies silently, so the
 # route matrix asserts the two still agree.
 readonly AUDIT_CRON="${AUDIT_CRON:-17 1 * * 1}"
+readonly DOCS_AUDIT_CRON="${DOCS_AUDIT_CRON:-47 2 1,15 * *}"
 readonly AUDIT_CLOSE_CRON="43 3 * * *"
 readonly CLEANUP_ARTIFACTS_CRON="0 6 * * *"
 readonly RECONCILE_BOT_PR_RUNS_CRON="17 * * * *"
@@ -192,6 +193,7 @@ classify_route() {
       trigger_kind="scheduled"
       case "${SCHEDULE:-}" in
         "$AUDIT_CRON") route="audit" ;;
+        "$DOCS_AUDIT_CRON") route="docs-audit" ;;
         "$AUDIT_CLOSE_CRON") route="audit-close" ;;
         "$CLEANUP_ARTIFACTS_CRON") route="cleanup-artifacts" ;;
         "$RECONCILE_BOT_PR_RUNS_CRON") route="reconcile-bot-pr-runs" ;;
@@ -266,7 +268,7 @@ classify_route() {
             error="operation 'evidence' needs a positive pr-number, got '${INPUT_PR_NUMBER:-}'"
           fi
           ;;
-        audit)
+        audit | docs-audit)
           route="${OPERATION}"
           trigger_kind="${INPUT_TRIGGER_KIND:-manual}"
           ;;

package/loops/actions/collect-doc-drift/action.yml

@@ -0,0 +1,29 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/collect-doc-drift/action.yml. Update with workflows update --force; consumer edits may be overwritten.
+name: Collect documentation drift
+description: |
+  Writes the documentation facts a script can establish on its own to
+  `/tmp/gh-aw/agent/doc-drift.json`: relative Markdown links that lead nowhere, and paths the
+  entry documents cite that no longer exist. Free, deterministic, no model.
+inputs:
+  entry-docs:
+    description: Comma-separated entry documents, whose cited paths are checked.
+    required: false
+    default: README.md,ARCHITECTURE.md,AGENTS.md,CLAUDE.md,CONTRIBUTING.md,docs/README.md
+  exclude:
+    description: Comma-separated path prefixes left out of the scan, such as archives.
+    required: false
+    default: .github/workflows/,.agents/,.claude/,.opencode/,node_modules/
+  output-path:
+    description: Path to write the JSON output.
+    required: false
+    default: /tmp/gh-aw/agent/doc-drift.json
+runs:
+  using: composite
+  steps:
+    - name: Collect documentation drift
+      shell: bash
+      env:
+        ENTRY_DOCS: ${{ inputs.entry-docs }}
+        EXCLUDE: ${{ inputs.exclude }}
+        OUTPUT_PATH: ${{ inputs.output-path }}
+      run: node "${GITHUB_ACTION_PATH}/collect-doc-drift.mjs"

package/loops/actions/collect-doc-drift/collect-doc-drift.mjs

@@ -0,0 +1,129 @@
+// Managed by @plainconceptsplatform/workflows. Source: loops/actions/collect-doc-drift/collect-doc-drift.mjs. Update with workflows update --force; consumer edits may be overwritten.
+//
+// Everything here is something a model would otherwise spend turns establishing, and could get
+// wrong. Existence only: whether a link's anchor resolves, or whether a sentence is still true,
+// is left to the agent.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, normalize } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// A report nobody can finish reading is a report nobody acts on, and it costs input tokens.
+const MAX_LISTED = 200;
+
+const FENCE = /^\s*(```|~~~)/;
+const INLINE_LINK = /(?<!!)\[[^\]]*\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g;
+const IMAGE_LINK = /!\[[^\]]*\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g;
+const CODE_SPAN = /`([^`\n]+)`/g;
+const CITED_PATH = /^\.?\/?[\w.-]+(\/[\w.-]+)*\/?$/;
+const EXTERNAL = /^[a-z][a-z0-9+.-]*:|^\/\//i;
+
+const splitList = (value) => (value ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+
+export const isExcluded = (path, prefixes) => prefixes.some((prefix) => path.startsWith(prefix));
+
+/** The file a link points at, or null when it does not point at a file in this repository. */
+export function linkTarget(fromFile, href) {
+  if (href.startsWith("#") || EXTERNAL.test(href)) return null;
+  const path = href.split(/[#?]/)[0];
+  if (path === "") return null;
+  let decoded = path;
+  try {
+    decoded = decodeURIComponent(path);
+  } catch {
+    // A literal % that is not an escape: the undecoded path is the one to check.
+  }
+  return normalize(decoded.startsWith("/") ? decoded.slice(1) : join(dirname(fromFile), decoded));
+}
+
+// A code span in prose often is a path, but `owner/repo` and `application/json` have the same
+// shape. Requiring an existing first segment keeps paths into this repository and drops those.
+export function citedPath(span, topLevelEntries) {
+  if (!span.includes("/") || !CITED_PATH.test(span)) return null;
+  const path = span.replace(/^\.?\//, "");
+  return topLevelEntries.has(path.split("/")[0]) ? path : null;
+}
+
+/** Walk a Markdown document line by line, skipping fenced code, where a link is an example. */
+export function* proseLines(markdown) {
+  let fenced = false;
+  let number = 0;
+  for (const line of markdown.split(/\r?\n/)) {
+    number += 1;
+    if (FENCE.test(line)) {
+      fenced = !fenced;
+      continue;
+    }
+    if (!fenced) yield { number, line };
+  }
+}
+
+export function scan({ files, entryDocs, read, exists, topLevelEntries }) {
+  const brokenLinks = [];
+  const missingPaths = [];
+  const seenCitations = new Set();
+
+  for (const file of files) {
+    const isEntry = entryDocs.includes(file);
+    for (const { number, line } of proseLines(read(file))) {
+      const withoutCode = line.replace(CODE_SPAN, "");
+      for (const pattern of [INLINE_LINK, IMAGE_LINK]) {
+        for (const [, href] of withoutCode.matchAll(pattern)) {
+          const target = linkTarget(file, href);
+          if (target !== null && !exists(target)) brokenLinks.push({ file, line: number, target: href });
+        }
+      }
+      if (!isEntry) continue;
+      for (const [, span] of line.matchAll(CODE_SPAN)) {
+        const path = citedPath(span, topLevelEntries);
+        const key = `${file}:${path}`;
+        if (path === null || seenCitations.has(key) || exists(path)) continue;
+        seenCitations.add(key);
+        missingPaths.push({ file, line: number, path });
+      }
+    }
+  }
+
+  return { brokenLinks, missingPaths };
+}
+
+function main() {
+  const entryDocs = splitList(process.env.ENTRY_DOCS);
+  const exclude = splitList(process.env.EXCLUDE);
+  const outputPath = process.env.OUTPUT_PATH ?? "/tmp/gh-aw/agent/doc-drift.json";
+
+  const tracked = execFileSync("git", ["ls-files", "-z"], { encoding: "utf8", maxBuffer: 1 << 28 })
+    .split("\0").filter(Boolean);
+  const files = tracked.filter((path) => path.endsWith(".md") && !isExcluded(path, exclude));
+  const trackedSet = new Set(tracked);
+  const exists = (path) => {
+    if (trackedSet.has(path)) return true;
+    // A directory is tracked only through its files, and a generated file not at all.
+    return existsSync(path) && (statSync(path).isDirectory() || statSync(path).isFile());
+  };
+
+  const { brokenLinks, missingPaths } = scan({
+    files,
+    entryDocs,
+    read: (path) => readFileSync(path, "utf8"),
+    exists,
+    topLevelEntries: new Set(tracked.map((path) => path.split("/")[0])),
+  });
+
+  const report = {
+    scannedDocuments: files.length,
+    entryDocuments: entryDocs.filter((path) => trackedSet.has(path)),
+    missingEntryDocuments: entryDocs.filter((path) => !trackedSet.has(path)),
+    brokenLinkCount: brokenLinks.length,
+    missingPathCount: missingPaths.length,
+    brokenLinks: brokenLinks.slice(0, MAX_LISTED),
+    missingPaths: missingPaths.slice(0, MAX_LISTED),
+  };
+
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, `${JSON.stringify(report, null, 2)}\n`);
+  console.log(`Scanned ${files.length} documents: ${brokenLinks.length} broken links, ${missingPaths.length} missing cited paths.`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/loops/actions/land-pull-request/action.yml

@@ -23,6 +23,14 @@ inputs:
     required: false
     default: Approved by the merge gate.
 
+  post-merge-event:
+    description: >-
+      repository_dispatch event type posted after a merge lands on the default branch. GitHub does
+      not always create a push run for a merge the App performs, so a consumer that deploys on push
+      opts into this event instead of relying on that run.
+    required: false
+    default: agentic-post-merge
+
 outputs:
   landed:
     description: "'merged', 'enqueued', or empty when nothing happened."
@@ -40,4 +48,6 @@ runs:
         HEAD_SHA: ${{ inputs.head-sha }}
         APPROVE: ${{ inputs.approve }}
         APPROVAL_BODY: ${{ inputs.approval-body }}
+        DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        POST_MERGE_EVENT: ${{ inputs.post-merge-event }}
       run: bash "${GITHUB_ACTION_PATH}/land-pull-request.sh"

package/loops/actions/land-pull-request/land-pull-request.sh

@@ -13,6 +13,18 @@ set -euo pipefail
 
 out() { echo "landed=$1" >> "${GITHUB_OUTPUT:-/dev/null}"; }
 
+# GitHub does not always create a push run for a merge the App performs. A consumer that deploys on
+# push listens for this dispatch instead, so the merge still deploys.
+dispatch_post_merge() {
+  [ "$base" = "${DEFAULT_BRANCH:-}" ] || return 0
+  gh api -X POST "repos/$REPO/dispatches" \
+    -f event_type="${POST_MERGE_EVENT:-agentic-post-merge}" \
+    -f "client_payload[sha]=$HEAD_SHA" \
+    -f "client_payload[pr]=$PR" \
+    -f "client_payload[base]=$base" >/dev/null ||
+    echo "::warning::The merge landed, but the ${POST_MERGE_EVENT:-agentic-post-merge} dispatch failed; a consumer that deploys on it did not start."
+}
+
 pr_json=$(gh pr view "$PR" --repo "$REPO" --json headRefOid,baseRefName,headRefName,state)
 state=$(jq -r .state <<<"$pr_json")
 [ "$state" = OPEN ] || { echo "#$PR is $state; nothing to land."; out ""; exit 0; }
@@ -43,6 +55,7 @@ if [ -z "$queue" ]; then
   # The branch goes as well: nothing else deletes it where `delete_branch_on_merge` is off.
   gh api -X DELETE "repos/$REPO/git/refs/heads/$head_ref" >/dev/null 2>&1 || true
   echo "Merged #$PR into $base."
+  dispatch_post_merge
   out merged
   exit 0
 fi
@@ -87,6 +100,7 @@ case "$status" in
     ;;
   merged)
     echo "#$PR merged into $base."
+    dispatch_post_merge
     out merged
     ;;
   *)

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

@@ -108,7 +108,7 @@ runs:
             'release-tag.yml',
             'agentics-checks.yml',
             'agentics-maintenance.yml',
-            ...['refine', 'implement', 'triage', 'apply-review', 'merge-gate', 'audit', 'release']
+            ...['refine', 'implement', 'triage', 'apply-review', 'merge-gate', 'audit', 'docs-audit', 'release']
               .map((route) => `agent-${route}.lock.yml`),
           ]);
           const ownedName = (path) => (path ?? '').split('/').pop() ?? '';

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

@@ -26,7 +26,8 @@ router_env() {
   sed -n "s/^  $1: *//p" "$ROUTER_YML" | head -1 | sed -e 's/^"\(.*\)"$/\1/' -e "s/^'\(.*\)'$/\1/"
 }
 AUDIT_CRON="$(router_env AUDIT_CRON)"
-export AUDIT_CRON
+DOCS_AUDIT_CRON="$(router_env DOCS_AUDIT_CRON)"
+export AUDIT_CRON DOCS_AUDIT_CRON
 
 # shellcheck source-path=SCRIPTDIR
 # shellcheck source=../classify-route/classify-route.sh
@@ -34,7 +35,7 @@ source "${HERE}/../classify-route/classify-route.sh"
 
 # Every worker route the package knows. The ones with a worker file here are installed; the
 # others must have no job in this router. Plumbing routes are in every router.
-ALL_WORKER_ROUTES=(refine implement triage apply-review merge-gate audit release)
+ALL_WORKER_ROUTES=(refine implement triage apply-review merge-gate audit docs-audit release)
 PLUMBING_ROUTES=(bot-approve evidence audit-close cleanup-artifacts reconcile-bot-pr-runs housekeeping validate)
 
 worker_installed() {
@@ -285,6 +286,13 @@ assert "a scheduled audit reports its trigger kind" scheduled \
 assert "a dispatched audit reports its trigger kind" manual \
   "$(route_field trigger-kind EVENT=workflow_dispatch OPERATION=audit INPUT_TRIGGER_KIND=manual)"
 
+assert_route "the docs audit slot reaches its route" docs-audit \
+  EVENT=schedule "SCHEDULE=${DOCS_AUDIT_CRON:-47 2 1,15 * *}"
+assert_route "a dispatched docs audit reaches its route" docs-audit \
+  EVENT=workflow_dispatch OPERATION=docs-audit
+assert "a scheduled docs audit reports its trigger kind, or its cheap exit never fires" scheduled \
+  "$(route_field trigger-kind EVENT=schedule "SCHEDULE=${DOCS_AUDIT_CRON:-47 2 1,15 * *}")"
+
 echo "── Prompt hygiene ────────────────────────────────────────────────────────"
 
 # Everything below a worker's frontmatter is the prompt. Three things must not be in one.
@@ -368,6 +376,15 @@ if worker_installed audit; then
     echo "FAIL: the audit slot cron is '${cron_line}' but env.AUDIT_CRON is '${AUDIT_CRON}'" >&2
   fi
 fi
+if worker_installed docs-audit; then
+  cron_line="$(sed -n 's/^ *- cron: "\([^"]*\)" # docs-audit slot.*/\1/p' "$ROUTER_YML" | head -1)"
+  if [ -z "$DOCS_AUDIT_CRON" ]; then
+    MIRROR_OK=0; echo "FAIL: work-router.yml defines no DOCS_AUDIT_CRON in its env: block" >&2
+  elif [ "$DOCS_AUDIT_CRON" != "$cron_line" ]; then
+    MIRROR_OK=0
+    echo "FAIL: the docs-audit slot cron is '${cron_line}' but env.DOCS_AUDIT_CRON is '${DOCS_AUDIT_CRON}'" >&2
+  fi
+fi
 # And nothing may go back to naming the CI workflow directly: a second literal is a second
 # thing to keep in step, and the one that gets forgotten is the one inside a jq filter.
 if [ "$(count -c '"App: CI"' "$ROUTER_YML")" -gt 2 ]; then
@@ -1317,6 +1334,19 @@ if [ -f "$AUDIT_CLOSE_YML" ] && worker_installed audit; then
     echo "FAIL: the audit backpressure query and audit-close disagree about stale-audit; abandoned reports would block every future audit" >&2
   fi
 
+  # The docs audit shares the chain, so it has the same two ways to go quiet: audit-close stops
+  # listing its reports, or its backpressure stops excluding the ones marked stale.
+  DOCS_AUDIT_WORKER_MD="${WORKFLOWS_DIR}/agent-docs-audit.md"
+  if [ -f "$DOCS_AUDIT_WORKER_MD" ]; then
+    docs_query="$(sed -n 's/^ *query: *"\(.*\)" *$/\1/p' "$DOCS_AUDIT_WORKER_MD" | head -1)"
+    if [[ "$docs_query" == *label:docs-audit*-label:stale-audit* ]] && grep -qF "'docs-audit'" "$AUDIT_CLOSE_YML"; then
+      PASS=$((PASS + 1))
+    else
+      AC_OK=0
+      echo "FAIL: audit-close and the docs-audit backpressure disagree; abandoned reports would stop every future docs audit" >&2
+    fi
+  fi
+
   if [ "$AC_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
@@ -1822,7 +1852,7 @@ LEAD_OK=1
 # A consumer has it at its root; this package keeps the template beside the workflows.
 CI_JSON="${HERE}/../../../opencode.ci.json"
 [ -f "$CI_JSON" ] || CI_JSON="${HERE}/../../templates/opencode/opencode.ci.json"
-for route in refine implement triage apply-review merge-gate audit release; do
+for route in refine implement triage apply-review merge-gate audit docs-audit release; do
   worker_md="${WORKFLOWS_DIR}/agent-${route}.md"
   [ -f "$worker_md" ] || continue
   lead=$(sed -n 's/^  AGENT_LEAD_MODEL: "\(.*\)"$/\1/p' "$worker_md")
@@ -1853,7 +1883,7 @@ PLUGINS_OK=1
 if ! grep -qF "(cd .opencode && npm install" "${WORKFLOWS_DIR}/shared/opencode-ci.md"; then
   PLUGINS_OK=0; echo "FAIL: the CI setup must install .opencode's dependencies or the harness plugins never load" >&2
 fi
-for route in refine implement triage apply-review merge-gate audit release; do
+for route in refine implement triage apply-review merge-gate audit docs-audit release; do
   worker_md="${WORKFLOWS_DIR}/agent-${route}.md"
   [ -f "$worker_md" ] || continue
   tier=$(sed -n 's/^  AGENT_TIER_MODEL: "\(.*\)"$/\1/p' "$worker_md")
@@ -2281,7 +2311,7 @@ if [ -f "$ERROR_REPORT_YML" ]; then
       # The worker names are built from a route list by a template literal, so expand that list
       # the same way rather than looking for filenames the file never spells out.
       sed -n "/const OWNED = new Set(\[/,/^          \]);\$/p" "$ERROR_REPORT_YML" |
-        grep -oE "'(refine|implement|triage|apply-review|merge-gate|audit|release)'" | tr -d "'" |
+        grep -oE "'(refine|implement|triage|apply-review|merge-gate|audit|docs-audit|release)'" | tr -d "'" |
         sed 's|^|agent-|; s|$|.lock.yml|' || true
     } | sort -u )
     shipped=$( {
@@ -2942,6 +2972,7 @@ fi
 ONE_AT_A_TIME_OK=1
 grep -qF 'The next landing releases the next one."' "${WORKFLOWS_DIR}/work-router.yml" ||
   { ONE_AT_A_TIME_OK=0; echo "FAIL: land-stack-child releases every free sibling at once" >&2; }
+# shellcheck disable=SC2015
 grep -qF 'echo "Released #$child of feature #$feature."' "${WORKFLOWS_DIR}/work-router.yml" &&
   grep -A1 -F 'echo "Released #$child of feature #$feature."' "${WORKFLOWS_DIR}/work-router.yml" | grep -qE '^\s+break$' ||
   { ONE_AT_A_TIME_OK=0; echo "FAIL: stack-landed releases every free child of the next feature at once" >&2; }
@@ -2950,6 +2981,19 @@ grep -qF -- '--base "$STACK_BRANCH" --limit 100 --json number,body' "${WORKFLOWS
 grep -qF 'releasedFeatures' "${HERE}/../housekeeping/action.yml" ||
   { ONE_AT_A_TIME_OK=0; echo "FAIL: housekeeping releases several children of one feature in a sweep" >&2; }
 if [ "$ONE_AT_A_TIME_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+# A repository variable AGENTIC_WORKFLOWS_DISABLED turns everything off: the router's two root jobs
+# (every other job needs one of them) and every workflow with a trigger of its own.
+OFF_OK=1
+for job in authorize classify; do
+  sed -n "/^  ${job}:\$/,/^    runs-on:/p" "${WORKFLOWS_DIR}/work-router.yml" | grep -qF "if: vars.AGENTIC_WORKFLOWS_DISABLED == ''" ||
+    { OFF_OK=0; echo "FAIL: the router's ${job} job ignores AGENTIC_WORKFLOWS_DISABLED" >&2; }
+done
+for f in "${WORKFLOWS_DIR}/authorize-bot-work.yml" "${WORKFLOWS_DIR}/release-tag.yml"; do
+  [ -f "$f" ] || continue
+  grep -qF "vars.AGENTIC_WORKFLOWS_DISABLED == ''" "$f" ||
+    { OFF_OK=0; echo "FAIL: $(basename "$f") ignores AGENTIC_WORKFLOWS_DISABLED" >&2; }
+done
+if [ "$OFF_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 # A stack child runs the feature branch's copy of the workflows, so the router brings the default
 # branch in before it dispatches one.
 if grep -qF 'bring $DEFAULT_BRANCH into $STACK_BRANCH before a child runs' "${WORKFLOWS_DIR}/work-router.yml"; then

package/loops/docs/diagrams.md

@@ -48,6 +48,7 @@ flowchart TD
     work -->|apply-review| wReview
     work -->|merge-gate| wGate
     work -->|audit| wAudit
+    work -->|docs-audit| wDocs
     work -->|release| wRelease
     triageOnly("dispatch-triage<br/>re-enters as the App, so the<br/>worker sees a trusted actor") --> wTriage
     wRefine("agent-refine")
@@ -55,6 +56,7 @@ flowchart TD
     wReview("agent-apply-review")
     wGate("agent-merge-gate<br/>one lock for the whole repo")
     wAudit("agent-audit")
+    wDocs("agent-docs-audit")
     wRelease("agent-release")
     wTriage("agent-triage")
     classify -.->|"cron or dispatch"| plumbing
@@ -487,8 +489,7 @@ before anything changes. Applying them one at a time produces contradictory comm
 
 ## agent-audit.md
 
-The only worker that 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 an issue and changes nothing.
 
 ```mermaid
 flowchart TD
@@ -528,6 +529,48 @@ reads them next time.
 
 ---
 
+## agent-docs-audit.md
+
+The audit's documentation sibling. Read-only, optional, and most of its work happens before the
+model starts: a repository with no recent commits never reaches it, and the facts a script can
+establish are on disk when it does.
+
+```mermaid
+flowchart TD
+    daStart("Work Router<br/>docs-audit route<br/>days 1 and 15, or dispatch") --> daBack
+    daBack{"Backpressure (rung 1)<br/>No open report?"}
+    daBack -.->|no| daIdle
+    daBack -->|yes| daMoved
+    daMoved{"Commits in 17 days,<br/>or a dispatch? (rung 1)"}
+    daMoved -.->|no| daIdle
+    daMoved -->|yes| daFacts
+    daFacts("Facts (rung 3)<br/>Broken links, missing paths,<br/>open issues, the standard") --> daRun
+    daRun("Compare (rung 5)<br/>Entry documents against<br/>the code and the standard") --> daDedupe
+    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"))
+    daQuiet(("Nothing to file<br/>the documentation is current"))
+    daIdle(("Idle<br/>no agent, no spend"))
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    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 daBack,daMoved,daDedupe decision
+    class daIdle idle
+    class daReport,daQuiet success
+```
+
+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.
+
+---
+
 ## agent-release.md
 
 Manual dispatch only. The agent writes prose; deterministic jobs do everything irreversible, and

package/loops/templates/agentics/agentics-app-errors.yml

@@ -87,7 +87,8 @@ env:
 jobs:
   collect:
     # Fork of a consumer: not their Azure, not their issues.
-    if: "!github.event.repository.fork"
+    # AGENTIC_WORKFLOWS_DISABLED, a repository variable with any value, turns the automation off.
+    if: "!github.event.repository.fork && vars.AGENTIC_WORKFLOWS_DISABLED == ''"
     runs-on: agents-arc
     timeout-minutes: 20
     # Load bearing, not decoration. The federated credential on the deploy identity trusts the

package/loops/templates/agentics/agentics-error-report.yml

@@ -58,7 +58,8 @@ env:
 jobs:
   report:
     # Fork of a consumer: the fleet is not theirs and neither is the report.
-    if: "!github.event.repository.fork"
+    # AGENTIC_WORKFLOWS_DISABLED, a repository variable with any value, turns the automation off.
+    if: "!github.event.repository.fork && vars.AGENTIC_WORKFLOWS_DISABLED == ''"
     runs-on: agents-arc
     timeout-minutes: 20
     concurrency: