@plainconceptsplatform/workflows 1.8.3 → 1.9.1

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/authorize-bot-work.yml

@@ -1,105 +1,107 @@
-# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/authorize-bot-work.yml. Update with `workflows update --force`; consumer edits may be overwritten.
-# Human adds implement/refine/direct/feature label → validates permission → bot adds bot-working
-# This ensures the bot is the actor for all agentic workflows.
-#
-# IMPORTANT: Only triggers for HUMAN actors. When the bot transitions refine→implement,
-# it adds bot-working itself, so authorize-bot-work must not fire again.
-name: "Authorize Bot Work"
-
-run-name: "Authorizing: ${{ github.event.issue.title }} (#${{ github.event.issue.number }})"
-
-on:
-  issues:
-    types: [labeled]
-
-permissions:
-  contents: read
-
-jobs:
-  authorize:
-    # Only trigger for work labels from HUMANS (not bots), and only if another bot run does not
-    # already own the issue.
-    #
-    # `review` is deliberately NOT excluded. It used to be, and that made the label a one-way
-    # door: the classifier refuses to route while `review` is set, so a person adding `refine`
-    # to a parked issue got no run, no comment and no error anywhere. Triage's own
-    # needs-maintainer verdict tells the maintainer to add `refine`, which could not work.
-    #
-    # A person adding a work label IS the human review the label was waiting for, so this
-    # workflow clears it below before handing the issue to the bot. The classifier's own guard
-    # stays as it is: it exists to stop the *bot* re-triggering itself, and by the time
-    # bot-working is added `review` is already gone.
-    if: >
-      (github.event.label.name == 'implement' ||
-       github.event.label.name == 'refine') &&
-      !contains(github.event.issue.labels.*.name, 'bot-working') &&
-      !endsWith(github.actor, '[bot]')
-    runs-on: [agents-aw, "affinity-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}"]
-    timeout-minutes: 5
-    concurrency:
-      group: authorize-${{ github.event.issue.number }}
-      cancel-in-progress: false
-    permissions:
-      contents: read
-      issues: write
-    steps:
-      - name: Check actor permission
-        id: check
-        env:
-          GH_TOKEN: ${{ github.token }}
-          ACTOR: ${{ github.actor }}
-        run: |
-          set -euo pipefail
-          
-          permission=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$ACTOR/permission" \
-            --jq '.permission' 2>/dev/null || echo "none")
-          
-          case "$permission" in
-            admin | maintain | write)
-              echo "authorized=true" >> "$GITHUB_OUTPUT"
-              echo "::notice::$ACTOR has $permission permission - authorized"
-              ;;
-            *)
-              echo "authorized=false" >> "$GITHUB_OUTPUT"
-              echo "::warning::$ACTOR has '$permission' permission - not authorized"
-              ;;
-          esac
-
-      - name: Checkout for App token action
-        if: steps.check.outputs.authorized == 'true'
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-
-      - name: Generate App token
-        if: steps.check.outputs.authorized == 'true'
-        id: app-token
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
-        with:
-          app-id: ${{ secrets.BOT_APP_ID }}
-          private-key: ${{ secrets.BOT_PRIVATE_KEY }}
-
-      - name: Bot takes the issue over
-        if: steps.check.outputs.authorized == 'true'
-        env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          ISSUE_NUMBER: ${{ github.event.issue.number }}
-          LABEL: ${{ github.event.label.name }}
-        run: |
-          set -euo pipefail
-
-          # Clear review FIRST. A person adding a work label is the human review the label was
-          # waiting for, and the classifier refuses to route an issue that still carries it, so
-          # removing it here is what makes the hand-off work at all. It also has to happen
-          # before bot-working, because that is the event the classifier reads: adding
-          # bot-working first would raise an event whose payload still shows review.
-          # --remove-label on an absent label is a no-op, so this is safe on a fresh issue.
-          # `stalled` goes with it: a person taking the issue on restarts the work, so the
-          # marker the janitor retries on must not survive into the new run.
-          gh issue edit "$ISSUE_NUMBER" --remove-label "review" --remove-label "stalled" 2>/dev/null ||
-            echo "::notice::no review or stalled label to clear on #$ISSUE_NUMBER"
-
-          echo "Adding bot-working label to issue #$ISSUE_NUMBER (triggered by $LABEL)"
-          gh issue edit "$ISSUE_NUMBER" --add-label "bot-working"
-
-          echo "::notice::bot-working label added - bot will now own the $LABEL workflow"
+# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/authorize-bot-work.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+# Human adds implement/refine/direct/feature label → validates permission → bot adds bot-working
+# This ensures the bot is the actor for all agentic workflows.
+#
+# IMPORTANT: Only triggers for HUMAN actors. When the bot transitions refine→implement,
+# it adds bot-working itself, so authorize-bot-work must not fire again.
+name: "Authorize Bot Work"
+
+run-name: "Authorizing: ${{ github.event.issue.title }} (#${{ github.event.issue.number }})"
+
+on:
+  issues:
+    types: [labeled]
+
+permissions:
+  contents: read
+
+jobs:
+  authorize:
+    # Only trigger for work labels from HUMANS (not bots), and only if another bot run does not
+    # already own the issue.
+    #
+    # `review` is deliberately NOT excluded. It used to be, and that made the label a one-way
+    # door: the classifier refuses to route while `review` is set, so a person adding `refine`
+    # to a parked issue got no run, no comment and no error anywhere. Triage's own
+    # needs-maintainer verdict tells the maintainer to add `refine`, which could not work.
+    #
+    # A person adding a work label IS the human review the label was waiting for, so this
+    # workflow clears it below before handing the issue to the bot. The classifier's own guard
+    # stays as it is: it exists to stop the *bot* re-triggering itself, and by the time
+    # bot-working is added `review` is already gone.
+    # AGENTIC_WORKFLOWS_DISABLED, a repository variable with any value, turns the automation off.
+    if: >
+      vars.AGENTIC_WORKFLOWS_DISABLED == '' &&
+      (github.event.label.name == 'implement' ||
+       github.event.label.name == 'refine') &&
+      !contains(github.event.issue.labels.*.name, 'bot-working') &&
+      !endsWith(github.actor, '[bot]')
+    runs-on: [agents-aw, "affinity-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}"]
+    timeout-minutes: 5
+    concurrency:
+      group: authorize-${{ github.event.issue.number }}
+      cancel-in-progress: false
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Check actor permission
+        id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ACTOR: ${{ github.actor }}
+        run: |
+          set -euo pipefail
+          
+          permission=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$ACTOR/permission" \
+            --jq '.permission' 2>/dev/null || echo "none")
+          
+          case "$permission" in
+            admin | maintain | write)
+              echo "authorized=true" >> "$GITHUB_OUTPUT"
+              echo "::notice::$ACTOR has $permission permission - authorized"
+              ;;
+            *)
+              echo "authorized=false" >> "$GITHUB_OUTPUT"
+              echo "::warning::$ACTOR has '$permission' permission - not authorized"
+              ;;
+          esac
+
+      - name: Checkout for App token action
+        if: steps.check.outputs.authorized == 'true'
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Generate App token
+        if: steps.check.outputs.authorized == 'true'
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_PRIVATE_KEY }}
+
+      - name: Bot takes the issue over
+        if: steps.check.outputs.authorized == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          LABEL: ${{ github.event.label.name }}
+        run: |
+          set -euo pipefail
+
+          # Clear review FIRST. A person adding a work label is the human review the label was
+          # waiting for, and the classifier refuses to route an issue that still carries it, so
+          # removing it here is what makes the hand-off work at all. It also has to happen
+          # before bot-working, because that is the event the classifier reads: adding
+          # bot-working first would raise an event whose payload still shows review.
+          # --remove-label on an absent label is a no-op, so this is safe on a fresh issue.
+          # `stalled` goes with it: a person taking the issue on restarts the work, so the
+          # marker the janitor retries on must not survive into the new run.
+          gh issue edit "$ISSUE_NUMBER" --remove-label "review" --remove-label "stalled" 2>/dev/null ||
+            echo "::notice::no review or stalled label to clear on #$ISSUE_NUMBER"
+
+          echo "Adding bot-working label to issue #$ISSUE_NUMBER (triggered by $LABEL)"
+          gh issue edit "$ISSUE_NUMBER" --add-label "bot-working"
+
+          echo "::notice::bot-working label added - bot will now own the $LABEL workflow"

package/loops/workflows/release-tag.yml

@@ -27,7 +27,9 @@ concurrency:
 jobs:
   tag:
     name: Tag and publish the release
+    # AGENTIC_WORKFLOWS_DISABLED, a repository variable with any value, turns the automation off.
     if: >-
+      vars.AGENTIC_WORKFLOWS_DISABLED == '' &&
       startsWith(github.event.head_commit.message, 'chore(release): v')
     runs-on: agents-arc
     timeout-minutes: 10

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
@@ -307,6 +318,10 @@ permissions:
 jobs:
   # Public repositories must check repository permission before an event can start a model.
   authorize:
+    # Off switch: a repository variable AGENTIC_WORKFLOWS_DISABLED, with any value, stops every
+    # route. Every other job needs this one or classify, so nothing runs. For a repository that has
+    # the workflows installed but is not ready for them.
+    if: vars.AGENTIC_WORKFLOWS_DISABLED == ''
     runs-on: [agents-aw, "affinity-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}"]
     timeout-minutes: 5
     permissions:
@@ -371,6 +386,8 @@ jobs:
           esac
 
   classify:
+    # The same off switch as authorize; jobs that need only classify stop here.
+    if: vars.AGENTIC_WORKFLOWS_DISABLED == ''
     runs-on: [agents-aw, "affinity-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}"]
     timeout-minutes: 5
     permissions:
@@ -678,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
@@ -735,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
@@ -1142,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'
@@ -1292,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 '{}')
@@ -1418,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
           }
@@ -1470,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.8.3",
+  "version": "1.9.1",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",