@plainconceptsplatform/workflows 1.9.0 → 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; }

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/workflows/agent-docs-audit.md

@@ -0,0 +1,266 @@
+---
+# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/agent-docs-audit.md. Update with `workflows update --force`; consumer edits may be overwritten.
+env:
+  # The model this worker's own session runs on. See agent-audit.md for why it names one.
+  AGENT_LEAD_MODEL: "forge/glm-5-2"
+  # Every harness tier on one model the CI's Forge account is granted; see agent-audit.md.
+  AGENT_TIER_MODEL: "plainconcepts/glm-5-2"
+  AGENT_FAST_MODEL: "plainconcepts/glm-5-2"
+  REPO_RULES: "Read-only documentation audit. Report only stale documentation you can prove with evidence from both the document and the code. Do not modify files, commit, push, or run write operations."
+  # What this repository counts as its entry documents, and what the scan leaves out. Archives,
+  # parked material and generated documents belong in the exclusions: a broken link in a record
+  # of the past is not drift.
+  DOCS_AUDIT_ENTRY_DOCS: "README.md,ARCHITECTURE.md,AGENTS.md,CLAUDE.md,CONTRIBUTING.md,docs/README.md"
+  DOCS_AUDIT_EXCLUDE: ".github/workflows/,.agents/,.claude/,.opencode/,node_modules/"
+  DOCS_AUDIT_FOCUS: "Components, modules or bounded contexts the documents list against the ones that exist. Counts that no longer hold. Infrastructure, hosting or tooling that was retired but is still described. Workflows, scripts and commands that no longer exist. Decisions superseded in practice that still read as current. Two documents stating the same fact differently."
+  # The Platform documentation standard, read before the agent starts. A repository that keeps
+  # its own may point this elsewhere. Empty skips the structure check.
+  DOCS_STANDARD_URL: "https://raw.githubusercontent.com/PlainConceptsPlatform/foundations/main/ai/DOCUMENTATION.md"
+  # No commit in this many days means nothing can have drifted since the last run, so a scheduled
+  # run stops before the model starts. 17 is the longest gap between runs on days 1 and 15.
+  DOCS_AUDIT_QUIET_DAYS: "17"
+  GIT_AUTHOR_NAME: "github-actions[bot]"
+  GIT_AUTHOR_EMAIL: "github-actions[bot]@users.noreply.github.com"
+  GIT_COMMITTER_NAME: "github-actions[bot]"
+  GIT_COMMITTER_EMAIL: "github-actions[bot]@users.noreply.github.com"
+description: |
+  Read-only documentation audit. Checks that the repository's documentation still matches its
+  code and the Platform documentation standard. When it does not, files a single issue of
+  findings with evidence from both sides, labelled `docs-audit` + `refine`, so Refine sizes it
+  and splits it into one issue per finding. When the documentation is current, files nothing.
+
+  Router-only worker: triggered exclusively via workflow_call from work-router.yml.
+  Contract input: trigger-kind(scheduled|manual).
+  The router owns the fortnightly schedule and manual dispatch.
+
+  The `skip-if-match` below is backpressure: one unactioned report is enough, because a second
+  one would mostly restate the first.
+
+name: "Agent: Docs Audit"
+
+# Shared: network policy only. This workflow owns its Safe Outputs and OpenCode configuration.
+# permissions, engine, model and runs-on cannot be shared , see shared/platform-defaults.md.
+imports:
+  - github/gh-aw/.github/workflows/shared/opencode.md@v0.87.5
+  - shared/platform-defaults.md
+  - shared/opencode-ci.md
+
+on:
+  workflow_call:
+    inputs:
+      trigger-kind:
+        description: "Docs audit trigger: scheduled or manual"
+        required: false
+        type: string
+        default: manual
+
+  # Rung 1. `-label:stale-audit` keeps this from becoming a stop: audit-close labels a report
+  # nobody actioned, which frees the slot and lists it in the "Needs a human" digest. Without it
+  # one abandoned report would disable this worker for good, with a green run every fortnight.
+  skip-if-match:
+    query: "is:issue is:open label:docs-audit -label:stale-audit"
+    max: 1
+
+  # gh-aw folds the top-level `if:` into activation without depending on the job it reads, so
+  # the reference would resolve to '' and the agent would never run.
+  needs: [recent_commits]
+
+if: needs.recent_commits.outputs.changed == 'true'
+
+runs-on: agents-arc
+runs-on-slim: agents-arc
+
+secrets:
+  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
+engine:
+  id: opencode
+  version: "1.2.14"
+  env:
+    OPENAI_BASE_URL: https://forge.plainconcepts.com/v1
+
+model: openai/glm-5-2
+
+max-turns: 150
+max-turn-cache-misses: 1500
+max-ai-credits: 2500
+
+permissions: read-all
+
+steps:
+  - name: List what is already tracked
+    uses: ./.github/actions/list-open-issues
+    with:
+      token: ${{ github.token }}
+      repo: ${{ github.repository }}
+  - name: Collect documentation drift
+    uses: ./.github/actions/collect-doc-drift
+    with:
+      entry-docs: ${{ env.DOCS_AUDIT_ENTRY_DOCS }}
+      exclude: ${{ env.DOCS_AUDIT_EXCLUDE }}
+  # Fetched here rather than by the agent, whose network is closed. A standard that cannot be
+  # read costs the structure check, not the run: the prompt says to report it.
+  - name: Fetch the documentation standard
+    env:
+      STANDARD_PATH: /tmp/gh-aw/agent/documentation-standard.md
+    run: |
+      set -uo pipefail
+      mkdir -p "$(dirname "$STANDARD_PATH")"
+      if [ -n "$DOCS_STANDARD_URL" ] && curl -fsSL --max-time 30 "$DOCS_STANDARD_URL" -o "$STANDARD_PATH"; then
+        echo "Read the documentation standard from $DOCS_STANDARD_URL"
+      else
+        rm -f "$STANDARD_PATH"
+        echo "::warning::No documentation standard could be read from '${DOCS_STANDARD_URL}'. The audit runs without its structure check."
+      fi
+
+jobs:
+  # The cheap exit. A repository with no commits since the last run cannot have drifted, and a
+  # full agent run to say so would hold half of a two-machine fleet. A dispatch always runs: a
+  # person asking for an audit has a reason.
+  recent_commits:
+    runs-on: agents-arc
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      changed: ${{ steps.commits.outputs.changed }}
+    steps:
+      - name: Count recent commits on the default branch
+        id: commits
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          TRIGGER_KIND: ${{ inputs.trigger-kind }}
+          QUIET_DAYS: ${{ env.DOCS_AUDIT_QUIET_DAYS }}
+        run: |
+          set -uo pipefail
+          if [ "$TRIGGER_KIND" != "scheduled" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          since="$(date -u -d "${QUIET_DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ)"
+          # An unanswered API call must not read as "nothing changed": that is a green run that
+          # audited nothing. Run the audit instead.
+          if ! commits="$(gh api "repos/${REPO}/commits?since=${since}&per_page=1" --jq 'length')"; then
+            echo "::warning::Could not list recent commits; running the audit anyway."
+            commits=1
+          fi
+          if [ "$commits" = "0" ]; then
+            echo "No commits since ${since}: nothing can have drifted, so the agent does not run."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+  conclude:
+    needs: [activation, agent, safe_outputs]
+    if: >
+      needs.agent.result == 'success' &&
+      needs.safe_outputs.result == 'success' &&
+      needs.safe_outputs.outputs.process_safe_outputs_processed_count != '0'
+    runs-on: agents-arc
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Checkout workflow actions
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Create bot token
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          client-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_PRIVATE_KEY }}
+      # The safe_outputs job already created the issue. Only the labels are left, and they are
+      # applied with the App token so that `refine` reaches the router as a trusted event.
+      - name: Apply labels to the report
+        if: needs.safe_outputs.outputs.created_issue_number != ''
+        uses: ./.github/actions/add-issue-labels
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          issue-number: ${{ needs.safe_outputs.outputs.created_issue_number }}
+          labels: |
+            docs-audit
+            refine
+
+  # An agent that ended without a report or a noop would otherwise be a green run that audited
+  # nothing; see the same job in agent-audit.md.
+  empty_run:
+    needs: [agent, safe_outputs]
+    if: >
+      needs.agent.result == 'success' &&
+      needs.safe_outputs.outputs.process_safe_outputs_processed_count == '0'
+    runs-on: agents-arc
+    permissions:
+      contents: read
+    steps:
+      - name: Report a docs audit that produced no outcome
+        env:
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          echo "::error::The docs audit agent finished without emitting a report or a noop. Nothing was filed and no reason was given, so this run is a failure rather than a clean audit. ${RUN_URL}"
+          exit 1
+
+safe-outputs:
+  # A failed run is already a red run. An issue per failure buries the real backlog.
+  report-failure-as-issue: false
+  threat-detection: false
+  create-issue:
+    max: 1
+
+# Reads documents and the code they describe, and writes one issue. Unobserved so far: audit, the
+# nearest worker, takes about 45 minutes over a whole repository, and this one reads less.
+timeout-minutes: 60
+---
+
+1. This is a read-only documentation audit. Do not modify any file, do not commit, and do not
+   push. Adhere to ${{ env.REPO_RULES }}.
+
+2. Read the facts already collected for you, so you do not re-derive them:
+   - `/tmp/gh-aw/agent/doc-drift.json`: `brokenLinks` and `missingPaths`, each with its file and
+     line, plus `missingEntryDocuments`. These are established; do not check them again.
+   - `/tmp/gh-aw/agent/documentation-standard.md`: the Platform documentation standard. If this
+     file does not exist, skip step 4 and say so in one line of the report.
+   - `/tmp/gh-aw/agent/open-issues.json`: every open issue with its title and labels.
+
+3. Read the entry documents in `doc-drift.json`, then compare what they state with the code.
+   Look for: ${{ env.DOCS_AUDIT_FOCUS }}
+
+   Every finding needs evidence on both sides: the document's `file:line` and what it says, and
+   the `file:line` or directory that shows otherwise. A claim you cannot back with both is not a
+   finding. Prefer what misleads a reader acting on it over what is merely imprecise, and do not
+   report style, tone or missing polish.
+
+4. Compare the repository's documentation structure with the standard. Report a required
+   section that is missing, or that exists and is empty. A section the standard marks as not
+   applicable to this kind of repository is not a finding.
+
+5. Group the broken links and missing paths from step 2 into findings by document or by cause,
+   such as one renamed directory, rather than one finding per link. State their counts as they
+   appear in `doc-drift.json`.
+
+6. Discard any finding already tracked in `open-issues.json`. Exact-title duplicates are rejected
+   for you; your job is the ones worded differently that mean the same thing.
+
+   Before filing, call `memory_smart_search` for prior documentation audits of this repository
+   and drop any finding that was reported and consciously not acted on. After you have decided
+   what to file, call `memory_save` once with the date and, for each finding, its file, a
+   one-line description and its disposition. Keep it short; it is read by the next audit.
+
+7. If no finding is left, call `noop` and stop. Filing nothing is the right outcome when the
+   documentation is current.
+
+8. Call `create_issue` **once** with title "Docs audit: <date>". Do NOT specify labels, the
+   conclude job applies them. List every finding, the most misleading first, each with:
+   - the document's `file:line` and the stale statement;
+   - the evidence from the code, with its `file:line` or path;
+   - what the document should say, or the section that has to be added.
+
+   The issue goes to Refine, which sizes it and splits it into one issue per finding, so write
+   each finding to survive that: self-contained, naming its own files, never "as above".
+
+   Refer to people by role, never by name, and include no personal contact details, even when
+   a document you are quoting contains them.

package/loops/workflows/work-router.yml

@@ -83,6 +83,9 @@ run-name: >-
   && inputs.operation == 'audit'
   && format('Agent: Audit - manual{0}', '')
   || github.event_name == 'workflow_dispatch'
+  && inputs.operation == 'docs-audit'
+  && format('Agent: Docs Audit - manual{0}', '')
+  || github.event_name == 'workflow_dispatch'
   && inputs.operation == 'release'
   && format('Agent: Release{0}', '')
   || github.event_name == 'workflow_dispatch'
@@ -91,6 +94,9 @@ run-name: >-
   && github.event.schedule == '17 1 * * 1'
   && format('Agent: Audit - weekly{0}', '')
   || github.event_name == 'schedule'
+  && github.event.schedule == '47 2 1,15 * *'
+  && format('Agent: Docs Audit - fortnightly{0}', '')
+  || github.event_name == 'schedule'
   && github.event.schedule == '43 3 * * *'
   && format('Agentics: Audit Close - daily{0}', '')
   || github.event_name == 'schedule'
@@ -125,6 +131,9 @@ env:
   # first and the two of them consume the whole fleet. Pick a free slot per repository: see
   # "Scheduling across repositories" in the package README.
   AUDIT_CRON: "17 1 * * 1"
+  # The same idea for the documentation audit, if it is installed: see the same section of the
+  # package README. Two days a month, so a slot is a pair of days rather than a weekday.
+  DOCS_AUDIT_CRON: "47 2 1,15 * *"
   # The bot identities whose label changes and pull requests this router trusts. Space
   # separated, and every login the same account can present: GitHub reports an App as
   # `name[bot]` on some endpoints and `app/name` on others, so both spellings belong here.
@@ -221,6 +230,7 @@ on:
   # Cron to route mapping lives in .github/actions/classify-route/classify-route.sh.
   schedule:
     - cron: "17 1 * * 1" # audit slot, mirrored from env.AUDIT_CRON by the installer
+    - cron: "47 2 1,15 * *" # docs-audit slot, mirrored from env.DOCS_AUDIT_CRON by the installer
     - cron: "43 3 * * *"
     - cron: "0 6 * * *"
     - cron: "17 * * * *"
@@ -241,6 +251,7 @@ on:
           - merge-train
           - evidence
           - audit
+          - docs-audit
           - audit-close
           - cleanup-artifacts
           - reconcile-bot-pr-runs
@@ -684,7 +695,12 @@ jobs:
                             gh issue view "$feature" --repo "$REPO" --json body --jq '.body // ""' 2>/dev/null \
                               | grep -oiE 'blocked by #[0-9]+' | grep -oE '[0-9]+' || true
                           } | sort -u ); do
-                gh issue view "$b" --repo "$REPO" --json state --jq '.state' 2>/dev/null | grep -qix open || continue
+                # A feature's own children are not what the feature waits on. Refine's tracker lists them
+                # in the feature body as "#N ... Blocked by #M", and reading those lines as the feature's
+                # blockers held every child behind its siblings, and the first one behind itself.
+                info=$(gh issue view "$b" --repo "$REPO" --json state,body 2>/dev/null) || continue
+                printf '%s' "$info" | jq -e '(.state // "" | ascii_downcase) == "open"' >/dev/null || continue
+                printf '%s' "$info" | jq -r '.body // ""' | grep -qF "<!-- split-parent: ${feature} -->" && continue
                 waiting="$waiting #$b"
               done
             fi
@@ -741,6 +757,7 @@ jobs:
           gh issue edit "$ISSUE_NUMBER" --repo "$REPO" --remove-label bot-working >/dev/null 2>&1 || true
           marker='<!-- stack-held -->'
           if ! gh api "repos/$REPO/issues/$ISSUE_NUMBER/comments?per_page=100" --jq '.[].body' 2>/dev/null | grep -qF "$marker"; then
+            # shellcheck disable=SC2016
             printf '%s\nHeld until%s have landed on the default branch: this feature builds on them. It keeps `implement` and is released when they merge.\n' "$marker" "$waiting" > /tmp/held.md
             gh issue comment "$ISSUE_NUMBER" --repo "$REPO" --body-file /tmp/held.md >/dev/null || true
           fi
@@ -1148,6 +1165,24 @@ jobs:
       BOT_PRIVATE_KEY: ${{ secrets.BOT_PRIVATE_KEY }}
       AGENTMEMORY_SECRET: ${{ secrets.AGENTMEMORY_SECRET }}
 
+  call-docs-audit:
+    needs: classify
+    if: needs.classify.outputs.route == 'docs-audit'
+    uses: ./.github/workflows/agent-docs-audit.lock.yml
+    concurrency:
+      group: docs-audit
+      cancel-in-progress: false
+    permissions: write-all
+    with:
+      trigger-kind: ${{ needs.classify.outputs.trigger-kind }}
+    secrets:
+      OPENAI_API_KEY: ${{ secrets.FORGE_API_KEY }}
+      CODEX_API_KEY: ${{ secrets.FORGE_API_KEY }}
+      COPILOT_GITHUB_TOKEN: ${{ secrets.FORGE_API_KEY }}
+      BOT_APP_ID: ${{ secrets.BOT_APP_ID }}
+      BOT_PRIVATE_KEY: ${{ secrets.BOT_PRIVATE_KEY }}
+      AGENTMEMORY_SECRET: ${{ secrets.AGENTMEMORY_SECRET }}
+
   call-release:
     needs: [classify, authorize]
     if: needs.classify.outputs.route == 'release' && needs.authorize.outputs.trusted == 'true'
@@ -1298,6 +1333,7 @@ jobs:
                   # each cut from the same branch, and every landing left the others conflicting. The
                   # next landing releases the next child. A held child with no `Blocked by` of its
                   # own (held because a sibling was in flight) is free once it carries the hold marker.
+                  # shellcheck disable=SC2086
                   for child in $(printf '%s\n' $children | sort -n); do
                     [ "$child" = "$closed_issue" ] && continue
                     meta=$(gh issue view "$child" --repo "$REPO" --json state,labels,body 2>/dev/null || echo '{}')
@@ -1424,7 +1460,11 @@ jobs:
               gh api "repos/$REPO/issues/$1/dependencies/blocked_by" --jq '.[] | select(.state == "open") | .number' 2>/dev/null || true
               for b in $(gh issue view "$1" --repo "$REPO" --json body --jq '.body // ""' 2>/dev/null \
                            | grep -oiE 'blocked by #[0-9]+' | grep -oE '[0-9]+' | sort -u || true); do
-                gh issue view "$b" --repo "$REPO" --json state --jq '.state' 2>/dev/null | grep -qix open && echo "$b" || true
+                # The feature's own children, listed in its tracker with their own "Blocked by", are not blockers.
+                info=$(gh issue view "$b" --repo "$REPO" --json state,body 2>/dev/null) || continue
+                printf '%s' "$info" | jq -e '(.state // "" | ascii_downcase) == "open"' >/dev/null || continue
+                printf '%s' "$info" | jq -r '.body // ""' | grep -qF "<!-- split-parent: $1 -->" && continue
+                echo "$b"
               done
             } | grep -vx "$parent" | sort -u || true
           }
@@ -1476,6 +1516,7 @@ jobs:
             fi
             # One child per feature, the lowest-numbered free one; each landing on the feature branch
             # releases the next (land-stack-child), so siblings never build side by side.
+            # shellcheck disable=SC2086
             for child in $(printf '%s\n' ${next_children[$feature]} | sort -n); do
               own=$(gh issue view "$child" --repo "$REPO" --json body --jq '.body // ""' 2>/dev/null \
                 | grep -oiE 'blocked by #[0-9]+' | grep -oE '[0-9]+' | sort -u || true)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/workflows",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",