feat(workflows): package fail-closed registry audit

AGENTS.md

@@ -41,6 +41,20 @@ add CODEOWNERS-based merge gates until multiple independent maintainers exist.
   realistic tenant-isolation, migration, rollback, compatibility, and
   concurrency tests.
 
+## Workflow registry audit
+
+- Keep the detector read-only. It may classify active identities that are
+  absent from an exact protected tree as candidates; it must never disable,
+  enable, edit, or rerun workflows.
+- Derive audit identity from an independently resolved 40-hex protected SHA
+  plus a live protected-ref pre/post check. Registry rows, `dynamic/` paths,
+  and transport headers are not source authority.
+- Require exact JSON-decoder types for containers and for `ref` / commit
+  `sha` / tree `sha` members before any equality test.
+- Keep the production module under `pg_llm_batch`, the console script
+  `pg-llm-batch-workflow-audit`, and the operator/ADR/doctoring/CHANGELOG
+  contract synchronized.
+
 ## Provider retry invariant
 
 Automatic provider retries are restricted to idempotent GET operations. The

ARCHITECTURE.md

@@ -63,6 +63,19 @@ does not require either host and retains standalone operation. When embedded,
 tenant scope is a local control-plane identity and not model- or
 provider-returned data.
 
+## Workflow registry audit
+
+`pg-llm-batch-workflow-audit` is a packaged read-only control-plane detector.
+It compares the GitHub Actions registry to one exact protected commit and
+reports active repository-backed identities that are absent from that tree as
+`active_absent_workflows` candidates. Platform-managed `dynamic/` identities
+are receipted and never treated as deleted YAML. The tool does not mutate
+workflow state, select tenant scope, or perform provider I/O.
+
+Operators install the package and run the console script. A moving protected
+ref, truncated tree, pagination drift, rate limit, or hostile identity-member
+type fails closed. Candidate review remains a human control-plane decision.
+
 ## Verification boundary
 
 Deterministic gates cover strict tenant validation, standalone compatibility,

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Read-only workflow-registry audit (`pg-llm-batch-workflow-audit`) that binds one receipt to an exact protected commit, verifies the live protected ref before and after the read, classifies active repository-backed identities missing from that tree as `active_absent_workflows` candidates only, receipts GitHub-managed `dynamic/` identities without treating them as orphans, and fails closed on hostile identity-member types, truncated trees, pagination drift, and rate limits. The tool never disables or edits workflows.
 - Read-only exact-head release acceptance that builds wheel and source distribution artifacts twice from clean Git archives, proves byte-identical SHA-256 identity, records bounded canonical evidence, and keeps publication and attestation authority separate.
 - Optional bounded provider output/error-file lifetime controls for batch creation, with exact local validation before credential resolution and backward-compatible omission for provider-neutral callers.
 - Trusted tenant-scoped durable lifecycle identities for shared-table MSA deployments, including `TenantDurableBatchAPIClient`, tenant-qualified persistence and read helpers, transaction-local PostgreSQL context, forced default-deny row-level security, and explicit standalone compatibility.

CLAUDE.md

@@ -27,3 +27,7 @@
 - Maintain 100% production statement, branch, and public-docstring coverage.
   Add realistic migration, rollback, compatibility, security, and
   tenant-isolation tests before implementation changes.
+- Keep the workflow-registry auditor read-only, packaged as
+  `pg_llm_batch.workflow_registry_audit` / `pg-llm-batch-workflow-audit`,
+  exact-type fail-closed on identity members, and documented in README,
+  architecture, ADR, doctoring, and CHANGELOG.

README.md

@@ -57,6 +57,7 @@ than a second database-side network authority.
 | DDL subset | `pg_llm_batch/schema.sql` |
 | Readiness (`/healthz`) | `pg_llm_batch/health.py` |
 | CLI | `pg_llm_batch/cli.py` |
+| Read-only workflow registry audit | `pg_llm_batch/workflow_registry_audit.py` |
 
 ## Requirements
 
@@ -154,6 +155,27 @@ python -m pg_llm_batch health   # prints the report, exit 0 ready / 1 not ready
 The Docker `HEALTHCHECK` and the compose `postgres` service both gate on the
 same `pg_llm_batch_health_check()` SQL function.
 
+### Workflow registry audit
+
+Detect active GitHub Actions identities that are missing from an exact
+protected source tree. The command is read-only: it never disables, edits, or
+reruns workflows. Review `active_absent_workflows` yourself. GitHub-managed
+`dynamic/` identities are listed but are not orphan candidates.
+
+```bash
+export GITHUB_TOKEN="$(gh auth token)"   # contents:read + actions:read
+pg-llm-batch-workflow-audit \
+  --repository ContextualWisdomLab/pg-llm-batch \
+  --protected-ref main \
+  --protected-sha "$(git rev-parse origin/main)"
+```
+
+Exit `0` means the protected ref stayed on the supplied SHA and no
+repository-backed orphan candidates were found. Exit `2` prints a JSON receipt
+with candidates for a separate review. Exit `1` is a fail-closed audit error.
+See [`docs/doctoring/workflow-registry-audit.md`](docs/doctoring/workflow-registry-audit.md)
+for token scope, rate-limit evidence, and recovery.
+
 ---
 
 ## Durable lifecycle modes

docs/adr/0016-workflow-registry-audit.md

@@ -0,0 +1,84 @@
+# ADR 0016: Read-only exact-SHA workflow registry audit
+
+- **Status:** Accepted for the read-only detector slice
+- **Date:** 2026-08-16
+
+## Context
+
+GitHub Actions can retain active workflow identities after their repository
+YAML is removed, or can register platform-managed `dynamic/` identities that
+never had a protected-tree blob. Operators need a fail-closed way to list those
+identities against one immutable protected commit. Automatic disable, rerun, or
+YAML rewrite would change production control-plane state from a detector.
+
+GitHub's Git database and Actions registry are separate evidence sources. A
+tree response `sha` is a tree object identity, not a commit SHA. A multi-page
+registry read can splice two registry generations even when `total_count` is
+unchanged. JSON subclasses can lie about equality if identity members are
+compared before an exact-type check.
+
+NIST SP 800-218 (SSDF) and SLSA v1.0 treat build-system integrity as a
+provenance control: verify the source that is supposed to produce automation
+before changing that automation. in-toto's farm-to-table argument is the same
+shape: bind an observation to an exact artifact identity rather than to a
+moving name.
+
+## Decision
+
+`pg_llm_batch.workflow_registry_audit` is a packaged, installable, read-only
+auditor.
+
+1. Transport is GET-only to `https://api.github.com`, path-only, no redirects,
+   finite timeout, default TLS verification, no automatic retry.
+2. The CLI always verifies the live protected ref before and after the SHA
+   audit. Library callers may classify one SHA without live-ref checks.
+3. Commit objects are resolved first; tree reads use `commit.tree.sha`.
+4. Multi-page registries require a second identical pass.
+5. Active repository-backed paths absent from the exact tree are candidates
+   only. `dynamic/` identities are receipted and never orphaned.
+6. Exact decoder types are required for containers and for identity members
+   before any `==` / `!=`.
+7. Exit codes are `0` (clean), `1` (failed closed), and `2` (candidates).
+8. The tool never disables, enables, edits, or reruns workflows.
+
+## Consequences
+
+Operators can install `pg-llm-batch` and run
+`pg-llm-batch-workflow-audit` without a special PYTHONPATH. Coverage,
+docstring, and compile gates now see the production module because it lives
+under `pg_llm_batch`. A buyer can distinguish a moving branch, a truncated
+tree, a rate-limit, and a true orphan candidate.
+
+The detector does not replace branch protection, required reviews, or a human
+decision to disable a workflow. False confidence from a stale PR body or from
+comparing a tree SHA to a commit SHA is rejected.
+
+## Rollback
+
+Rollback is code-only: remove the package module, console script, checkout
+shim, ADR, doctoring, changelog, and regression files. No database migration
+or Actions mutation is required. Adding mutation to this tool requires a
+separate reviewed control-plane contract.
+
+## References
+
+GitHub. (n.d.). *REST API endpoints for GitHub Actions workflows*. GitHub Docs.
+Retrieved August 16, 2026, from
+https://docs.github.com/en/rest/actions/workflows
+
+GitHub. (n.d.). *REST API endpoints for Git trees*. GitHub Docs. Retrieved
+August 16, 2026, from
+https://docs.github.com/en/rest/git/trees
+
+National Institute of Standards and Technology. (2022). *Secure software
+development framework (SSDF) version 1.1: Recommendations for mitigating the
+risk of software vulnerabilities* (NIST SP 800-218).
+https://doi.org/10.6028/NIST.SP.800-218
+
+The Linux Foundation. (2023). *Supply-chain Levels for Software Artifacts
+(SLSA) v1.0*. https://slsa.dev/spec/v1.0/
+
+Torres-Arias, S., Afzali, H., Kuppusamy, T. K., Curtmola, R., & Cappos, J.
+(2019). in-toto: Providing farm-to-table guarantees for bits and bytes. In
+*Proceedings of the 28th USENIX Security Symposium* (pp. 1393–1410). USENIX
+Association. https://www.usenix.org/conference/usenixsecurity19/presentation/torres-arias

docs/doctoring/workflow-registry-audit.md

@@ -0,0 +1,130 @@
+# Workflow registry audit doctoring
+
+## Purpose
+
+This record tells an operator how to detect GitHub Actions identities that are
+active in a repository registry but absent from an exact protected source tree,
+without disabling, editing, rerunning, or recreating any workflow.
+
+Use the installed command after `pip install pg-llm-batch` or an editable
+checkout. Do not treat a missing checkout-root module as the supported
+interface. The detector follows NIST SP 800-218 and SLSA v1.0 by binding the
+receipt to an exact source commit before any operator reviews a candidate.
+
+```bash
+export GITHUB_TOKEN="$(gh auth token)"   # contents:read + actions:read is enough
+pg-llm-batch-workflow-audit \
+  --repository ContextualWisdomLab/pg-llm-batch \
+  --protected-ref main \
+  --protected-sha "$(git rev-parse origin/main)"
+```
+
+Equivalent module form:
+
+```bash
+python -m pg_llm_batch.workflow_registry_audit \
+  --repository ContextualWisdomLab/pg-llm-batch \
+  --protected-ref main \
+  --protected-sha "$(git rev-parse origin/main)"
+```
+
+## What to do with the result
+
+- Exit `0`: the live protected ref still matches the supplied SHA, the registry
+  was stable across a complete pagination pass, and no active
+  repository-backed identity is missing from that exact tree. Keep operating.
+- Exit `2`: stdout is a JSON receipt whose `active_absent_workflows` lists
+  candidates only. Open a separate operator review. Do not disable those
+  workflows from this tool.
+- Exit `1`: the audit failed closed. Read the single stderr line, then correct
+  the repository selector, SHA, ref, token scope, rate-limit budget, or
+  truncated-tree condition and run the same command again.
+
+GitHub-managed `dynamic/` identities appear in `workflow_records` with
+`source_kind=platform_dynamic` and `source_present=null`. They are never
+orphans. Do not delete platform-managed identities because they lack a
+`.github/workflows/` blob.
+
+The library function `audit_repository_workflows` can classify one exact SHA
+without live-ref pre/post checks. The CLI always uses
+`audit_live_protected_ref_workflows` so a moving protected branch cannot
+certify a stale head.
+
+## Trust and security boundary
+
+The client sends path-only GET requests to the fixed origin
+`https://api.github.com`, disables redirects, and uses the default TLS
+verifier. It never retries automatically. Non-success bodies are not read.
+Rate-limit evidence is limited to HTTP 429 or HTTP 403 plus
+`X-RateLimit-Remaining: 0` or `Retry-After`.
+
+JSON objects, arrays, strings, integers, and booleans are accepted only as
+exact decoder built-in types. Identity members (`ref`, commit `sha`, tree
+`sha`) are type-checked before equality. A hostile subclass cannot certify the
+caller SHA while resolving a different tree.
+
+`GITHUB_TOKEN` is used only as an `Authorization` header. It is never copied
+into stdout, stderr, receipts, or exception cause chains.
+
+This tool does not select tenant scope, touch PostgreSQL, or mutate Actions
+state. It is a read-only control-plane detector for this repository and for
+hosts that embed `pg-llm-batch` as a module.
+
+## Recovery and rollback
+
+No schema, secret, or workflow mutation is performed. Recovery is to rerun the
+same read after correcting the failed input or GitHub condition. Rollback is
+removing the console script, package module, ADR, and this record. Reintroducing
+workflow disable/enable from this tool is not a routine rollback step.
+
+## Verification
+
+Permanent regression coverage requires that:
+
+- hostile `str` subclasses cannot satisfy commit, tree, or ref identity by
+  lying about equality;
+- raising identity subclasses become `WorkflowRegistryAuditError` without
+  leaking custom exception text;
+- `dynamic/` identities are receipted and never orphaned;
+- unknown workflow states fail closed;
+- multi-page registries are accepted only after a second identical pass;
+- truncated trees, moving protected refs, and oversize responses fail closed;
+- the console script `pg-llm-batch-workflow-audit` is declared in package
+  metadata; and
+- README, architecture, ADR, changelog, and this doctoring record all tell the
+  operator to review candidates instead of disabling workflows.
+
+## References
+
+GitHub. (n.d.). *REST API endpoints for GitHub Actions workflows*. GitHub Docs.
+Retrieved August 16, 2026, from
+https://docs.github.com/en/rest/actions/workflows
+
+GitHub. (n.d.). *REST API endpoints for Git commits*. GitHub Docs. Retrieved
+August 16, 2026, from
+https://docs.github.com/en/rest/git/commits
+
+GitHub. (n.d.). *REST API endpoints for Git trees*. GitHub Docs. Retrieved
+August 16, 2026, from
+https://docs.github.com/en/rest/git/trees
+
+GitHub. (n.d.). *REST API endpoints for Git references*. GitHub Docs. Retrieved
+August 16, 2026, from
+https://docs.github.com/en/rest/git/refs
+
+GitHub. (n.d.). *Rate limits for the REST API*. GitHub Docs. Retrieved August
+16, 2026, from
+https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api
+
+National Institute of Standards and Technology. (2022). *Secure software
+development framework (SSDF) version 1.1: Recommendations for mitigating the
+risk of software vulnerabilities* (NIST SP 800-218).
+https://doi.org/10.6028/NIST.SP.800-218
+
+The Linux Foundation. (2023). *Supply-chain Levels for Software Artifacts
+(SLSA) v1.0*. https://slsa.dev/spec/v1.0/
+
+Torres-Arias, S., Afzali, H., Kuppusamy, T. K., Curtmola, R., & Cappos, J.
+(2019). in-toto: Providing farm-to-table guarantees for bits and bytes. In
+*Proceedings of the 28th USENIX Security Symposium* (pp. 1393–1410). USENIX
+Association. https://www.usenix.org/conference/usenixsecurity19/presentation/torres-arias