docs: correct the workflow inventory and the collector client split

[sh4mbhavi]

What is wrong

Two pages describe the repository as it was, not as it is, and both errors send a contributor the wrong way.

docs/DevSecOps/workflow-documentation.md named ten of fourteen workflows

ci.compliance.yml, ci.gitleaks.yml, ops.branch-cleanup.yml and pr.size-warning.yml appeared nowhere on the page, which nevertheless generalised over the workflows as though the list were complete.

Four of its statements were wrong:

Page said	Actually
ci.grype.yml — "fail-build is false so findings are surfaced for review rather than blocking merges"	fail-build: true, severity-cutoff: critical. A critical finding fails the check.
ops.collector.yml "runs the audit engine collector on the engine-development branch"	Push trigger commented out, job carries if: false. It runs nothing, deliberately.
ops.workflow-cleanup.yml "runs on a schedule to delete old workflow run history"	The scheduled step is --dryRun=true. Deletion needs a manual dispatch with dry_run=false and confirm=DELETE. Schedule is Sundays 00:00 UTC, not Saturdays 23:32.
ci.validate-alerts.yml "does not do anything meaningful in its current state"	It runs promtool check rules and fails the build on a syntax error.
pr.size-warning.yml — undocumented, and the obvious reading is wrong	It does not comment on the PR. It emits a core.warning annotation and a job summary.

The fail-build one is the costly error: a contributor who believes the page is surprised by a red check they were told could not block them.

ops.workflow-cleanup.yml turned out to be worse than out of date. It is not a retention policy at all: the workflow passes RETENTION_DAYS: 30 and its dispatch input is described as "Delete runs older than this many days", but tools/workflow-cleanup/cleanup-workflows.js never reads that variable. It selects by how long a run took — under two minutes is deleted, two minutes or more is kept — across a single unpaginated page of 20 runs. A real deletion run would remove recent short runs and keep old long ones. Nothing here prunes by age, so this workflow should not be cited as retention evidence.

Two facts are now written down that were not:

• ci.opa-eval.yml evaluates engine/legacy/ and uploads a PDF and a JSON artifact. No policy verdict from it can fail a build — aggregator.py records a non-zero opa exit into the report JSON rather than raising — though a crash in either script still fails the job. Nothing in .github/workflows/ runs opa check, opa test or opa eval against the CIS or Essential Eight policies.
• ops.short-test.yml filters on .github/workflows/short-test.yml while the file is .github/workflows/ops.short-test.yml. Commit 155f82aa applied the ops. prefix and left the filter behind, so editing the canary no longer runs it.

engine/collectors/README.md said GraphClient was "shared across all Microsoft collectors"

It is not, and the gap is nearly half the registry. Resolving each DATA_COLLECTORS entry to the client its collect method declares gives 26 GraphClient and 22 PowerShellClient out of 48. Every Exchange Online and SharePoint Online setting AutoAudit reads comes through a cmdlet, because Graph does not expose it — so the page sent every new Exchange, Teams or SharePoint collector to the wrong client.

The page now leads with picking a client, shows a PowerShell worked example beside the Graph one, and states the mechanism that actually decides: engine/worker/tasks.py selects the client from the collector's registered ID prefix, before the class is instantiated, so a PowerShell collector registered under an entra. ID is handed a GraphClient and fails. That rule and the collect annotations agree for all 48 today. exchange.dns.dns_security_records is the carve-out and is explained.

Four smaller corrections on the same page: the imports in the examples are rooted at collectors., not engine.collectors.; the folder tree showed an m365/exchange|sharepoint|teams layout that does not exist; _pending/ — which holds the five Teams and two Purview collectors — was not mentioned; and two GraphClient guarantees were overstated. The client returns its cached token with no expiry check, so it is caching and not refresh, and get_all_pages stops at max_pages (default 100) and returns what it has rather than raising.

Verification

$ ls .github/workflows/
ci.backend-api.yml   ci.compliance.yml    ci.engine.yml        ci.frontend.yml
ci.gitleaks.yml      ci.grype.yml         ci.opa-eval.yml      ci.security.yml
ci.validate-alerts.yml
ops.branch-cleanup.yml  ops.collector.yml  ops.short-test.yml  ops.workflow-cleanup.yml
pr.size-warning.yml

workflows on disk : 14
named by the page : 14
on disk, unnamed  : none
named, not on disk: none

$ python3 -  # resolve every DATA_COLLECTORS entry to its collect() client
DATA_COLLECTORS entries: 48
  GraphClient: 26
  PowerShellClient: 22

The collector split is resolved by importing collectors.registry and reading each class's collect signature, not by counting git grep hits.

Merge order

The inventory is stated against this branch's base, which is the preview-deploy removal PR in this series: fourteen workflow files, after the three pr.preview-* files are gone. Merge that one first.

Caveat (GRC-D03)

Demonstrates policy-decision correctness against fixtures. No live tenant has been
collected, so this is not evidence of any organisation's control posture.

[sh4mbhavi]

Closing. This was stacked on the preview-deploy-removal branch, so its diff carried PR #378 as well as the doc corrections. PR 8's workflow-inventory count depends on #378 landing, so it will be reopened clean once #378 merges. No work lost; the branch is kept.