feat(automation): coordinate hourly organization readiness

.github/workflows/organization-commercial-readiness-loop-quality-ci.yml

@@ -0,0 +1,72 @@
+name: Organization Commercial Readiness Loop Quality CI
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - ".github/workflows/organization-commercial-readiness-loop.yml"
+      - ".github/workflows/organization-commercial-readiness-loop-quality-ci.yml"
+      - "scripts/ci/organization_commercial_readiness_loop.py"
+      - "organization_commercial_readiness_fixtures.py"
+      - "tests/test_organization_commercial_readiness_loop*.py"
+      - "docs/doctoring/organization-commercial-readiness-loop.md"
+      - "CHANGELOG.md"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: organization-commercial-readiness-loop-quality-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  exact-head-policy:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - name: Checkout exact source revision
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Install exact hash-verified quality dependencies
+        env:
+          PIP_DISABLE_PIP_VERSION_CHECK: "1"
+          PIP_NO_INPUT: "1"
+        shell: bash --noprofile --norc -e -o pipefail {0}
+        run: |
+          cat >"${RUNNER_TEMP}/organization-loop-quality-requirements.txt" <<'EOF'
+          coverage==7.15.2 --hash=sha256:b9a6367e4aff723e8ee8190836836124284e8fcd4265e307c844010cfa074f3f
+          iniconfig==2.1.0 --hash=sha256:9deba5723312380e77435581c6bf4935c94cbfab9b1ed33ef8d238ea168eb760
+          packaging==26.2 --hash=sha256:5fc45236b9446107ff2415ce77c807cee2862cb6fac22b8a73826d0693b0980e
+          pluggy==1.6.0 --hash=sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746
+          pygments==2.20.0 --hash=sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176
+          pytest==9.1.1 --hash=sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c
+          EOF
+          python -m pip install \
+            --only-binary=:all: \
+            --require-hashes \
+            -r "${RUNNER_TEMP}/organization-loop-quality-requirements.txt"
+
+      - name: Prove exact-head policy and full branch coverage
+        shell: bash --noprofile --norc -e -o pipefail {0}
+        run: |
+          test "$(git rev-parse HEAD)" = "${{ github.event.pull_request.head.sha }}"
+          python -m coverage run \
+            --branch \
+            -m pytest --import-mode=importlib tests/test_organization_commercial_readiness_loop*.py -q
+          python -m coverage report \
+            --include='scripts/ci/organization_commercial_readiness_loop.py' \
+            --show-missing \
+            --fail-under=100
+          python -m compileall -q \
+            scripts/ci/organization_commercial_readiness_loop.py \
+            organization_commercial_readiness_fixtures.py \
+            tests/test_organization_commercial_readiness_loop*.py
+          git diff --exit-code

.github/workflows/organization-commercial-readiness-loop.yml

@@ -0,0 +1,81 @@
+name: Organization Commercial Readiness Loop
+
+on:
+  schedule:
+    - cron: "7 * * * *"
+
+concurrency:
+  group: organization-commercial-readiness-loop
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  coordinate:
+    if: >-
+      github.repository == 'ContextualWisdomLab/.github' &&
+      github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+      ORGANIZATION: ContextualWisdomLab
+      ROTATION_SEED: ${{ github.run_number }}
+      MAX_REPOSITORIES: "200"
+      MAX_REVIEW_DISPATCHES: "1"
+      MAX_DEVELOPMENT_DISPATCHES: "1"
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.13.2
+        with:
+          egress-policy: block
+          allowed-endpoints: >-
+            api.github.com:443
+            github.com:443
+            objects.githubusercontent.com:443
+            release-assets.githubusercontent.com:443
+            results-receiver.actions.githubusercontent.com:443
+            *.actions.githubusercontent.com:443
+            *.blob.core.windows.net:443
+
+      - name: Checkout exact trusted coordinator source
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Coordinate one bounded fleet pass
+        env:
+          GH_TOKEN: ${{ secrets.PR_REVIEW_MERGE_TOKEN }}
+        shell: bash --noprofile --norc -e -o pipefail {0}
+        run: |
+          if [ -z "${GH_TOKEN:-}" ]; then
+            echo "::error::PR_REVIEW_MERGE_TOKEN is required; neither the reviewer credential nor repository-scoped GITHUB_TOKEN is accepted."
+            exit 1
+          fi
+          echo "::add-mask::$GH_TOKEN"
+          test "$(git rev-parse HEAD)" = "${GITHUB_SHA}"
+
+          python scripts/ci/organization_commercial_readiness_loop.py \
+            --organization "$ORGANIZATION" \
+            --rotation-seed "$ROTATION_SEED" \
+            --max-repositories "$MAX_REPOSITORIES" \
+            --max-review-dispatches "$MAX_REVIEW_DISPATCHES" \
+            --max-development-dispatches "$MAX_DEVELOPMENT_DISPATCHES" \
+            --json-output "$RUNNER_TEMP/organization-commercial-readiness-loop.json"
+          python -m json.tool "$RUNNER_TEMP/organization-commercial-readiness-loop.json" >/dev/null
+
+      - name: Preserve the exact fleet receipt
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: organization-commercial-readiness-${{ github.run_id }}-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/organization-commercial-readiness-loop.json
+          if-no-files-found: error
+          retention-days: 3

CHANGELOG.md

@@ -8,6 +8,7 @@ Semantic Versioning where the repository publishes a release.
 
 ### Added
 
+- Added an hourly organization commercial-readiness coordinator that discovers writable repositories, honors enabled dedicated writer leases and fully paginated live writer runs, refetches exact repository/workflow/run/PR state before dispatch, rotates bounded review-repair and opt-in NVIDIA OpenCode product-development targets, fails nonzero on fleet-wide inspection or dispatch outages, retains three-day JSON receipts, and keeps the existing 15-minute merge scheduler authoritative.
 - Added a trusted pull-request comment router for `@cwl-noema-review` and review-only `@opencode-agent` dispatches, with an organization sweep, exact-head receipts, repository allowlisting, fixed runners, immutable checkout pins, and a permanent 100% statement/branch/docstring quality gate.
 - Added exact-base `uv.lock` materialization that reconstructs standalone nested projects with a checksum-pinned official `uv` exporter, isolated frozen/offline execution, strict exact-pin and SHA-256 output validation, and complete Python 3.10/3.14 quality evidence.
 

docs/doctoring/organization-commercial-readiness-loop.md

@@ -0,0 +1,69 @@
+# Organization commercial-readiness coordinator
+
+## Decision
+
+ContextualWisdomLab uses one organization-central hourly coordinator for repositories that do not already have an enabled dedicated commercial, maintenance, review-repair, or product-development writer. The coordinator complements rather than duplicates the existing 15-minute organization merge scheduler.
+
+The coordinator may dispatch at most one review-repair workflow and one product-development workflow per hour. These may target different repositories, so review or check latency in one repository does not stop useful work in another. The coordinator never approves, merges, releases, edits source, or interprets a failed check as success by itself.
+
+## Why this is realistic
+
+A single workflow cannot safely write every repository merely because it runs in the organization `.github` repository. GitHub's default `GITHUB_TOKEN` is scoped to the repository containing the workflow; cross-repository Actions dispatch therefore requires an explicitly provisioned user or GitHub App credential with the required repository and Actions permissions. This control does not make every repository directly writable. It only considers repositories the live API reports as organization-owned, non-fork, enabled, non-archived, default-branch-bearing, and writable by the authenticated installation.
+
+The central job therefore refuses both repository-scoped and reviewer-scoped token fallbacks. It requires the maintainer-scoped `PR_REVIEW_MERGE_TOKEN`; `OPENCODE_APPROVE_TOKEN` remains isolated to the reviewer credential chain and `GITHUB_TOKEN` is not accepted for cross-repository coordination. The maintainer token is exposed only to the final dispatch shell step, not checkout, setup, artifact upload, or other third-party actions. The coordinator itself receives neither `NVIDIA_NIM_API_KEY` nor `COPILOT_GITHUB_TOKEN`. Model credentials remain inside separately reviewed repository-local or central workers.
+
+## Dynamic repository-writer lease
+
+An active workflow with a scheduled high-signal commercial/development/maintenance/review-repair identity owns the repository writer lease. A queued, in-progress, waiting, pending, or requested run with the same identity also owns a live lease. The organization coordinator skips that repository for the entire pass.
+
+A disabled workflow does not hold a lease. A manual-only workflow does not hold a lease unless it is already running. If an active high-signal workflow exists but its source cannot be read, the coordinator fails closed and treats the repository as leased. The organization-required merge scheduler is explicitly excluded from this classification because it is a governance gate rather than a product-code writer.
+
+The coordinator lists workflow metadata for every repository but fetches exact workflow source only for identities that can plausibly be a repository writer. This keeps API use proportional to writer candidates rather than every ordinary CI, packaging, or security workflow. Active-run and pull-request inventories remain fully paginated, including writers beyond the first 100 queued or running executions.
+
+Before every dispatch, the coordinator refetches the exact default-branch SHA, active workflow identities and source blobs, active runs, and open pull-request heads, bases, draft states, and update timestamps. Any change invalidates the predecessor snapshot. A newly appearing writer causes `skipped_writer_lease`; any other movement causes `skipped_state_changed`.
+
+## Review-repair boundary
+
+A repository with at least one non-draft pull request targeting its default branch may receive one `pr-review-fix-scheduler` repository dispatch. Draft and stacked pull requests are not treated as generic repair targets because the coordinator cannot safely infer their dependency order. The established central scheduler and autofix worker remain responsible for thread classification, current-head checks, path bounds, credential isolation, and whether a repair is actually warranted.
+
+The existing organization merge scheduler continues to own review dispatch, branch updates, exact-head approval evaluation, direct or automatic merge, and branch-protection compliance. The hourly coordinator does not create a second merge implementation.
+
+## Product-development boundary
+
+Product development is dispatched only when a repository has zero open pull requests and exposes one active, manual-only, explicitly marked workflow:
+
+```yaml
+# cwl-org-commercial-entrypoint: v1
+on:
+  workflow_dispatch:
+```
+
+The entrypoint must contain an explicit `concurrency` contract, use `NVIDIA_NIM_API_KEY`, omit `COPILOT_GITHUB_TOKEN`, have no schedule of its own, and carry a commercial/product-development identity. This opt-in prevents the central coordinator from guessing that an unrelated manual workflow can safely modify product source. Repositories with an existing schedule keep their own lease and are never double-dispatched.
+
+The repository-local entrypoint remains responsible for its own bounded editable paths, tests, 100% production statement and branch coverage, public docstrings, package and security verification, exact-head publication, and pull-request creation. A missing compliant entrypoint is a deliberate no-op, not permission to inject a generic writer into that repository.
+
+## Failure, evidence, and operations
+
+The schedule runs at minute 7 rather than minute 0 to reduce exposure to the documented start-of-hour GitHub Actions load spike. The central workflow has no `workflow_dispatch` entrypoint, so branch-selected coordinator source cannot be executed; scheduled execution occurs only from protected default `main`. Local operators may use the script's `--dry-run` mode from a reviewed checkout without adding a central manual workflow entrypoint.
+
+Organization, workflow, active-run, and pull-request inventories are paginated. One inaccessible repository is recorded as an inspection error while other independently safe repositories continue. A run fails nonzero when every selected repository inspection fails or when every planned dispatch fails; partial, independently contained failures remain visible without discarding successful work.
+
+Each run writes one deterministic JSON receipt and the same bounded evidence to the GitHub Actions job summary. The JSON is uploaded through the immutable, SHA-pinned artifact action with a three-day retention period. Artifact upload receives no maintainer or model credential. The receipt proves only coordinator observations and downstream dispatch acceptance; it is not merge, release, or product-quality evidence.
+
+No queued, pending, skipped-required, cancelled, absent, stale-head, predecessor-head, synthetic-merge-only, or failed check is converted to passing evidence. The coordinator's successful dispatch means only that exact state was revalidated and a bounded downstream workflow was accepted by GitHub.
+
+Rollback is removal or disabling of `.github/workflows/organization-commercial-readiness-loop.yml`. Repository-local dedicated loops and the existing 15-minute merge scheduler remain independently operational.
+
+## APA 7 references
+
+GitHub. (n.d.). *Automatic token authentication*. GitHub Docs. Retrieved August 8, 2026, from https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication
+
+GitHub. (n.d.). *Events that trigger workflows*. GitHub Docs. Retrieved August 8, 2026, from https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows
+
+GitHub. (n.d.). *REST API endpoints for artifacts*. GitHub Docs. Retrieved August 8, 2026, from https://docs.github.com/en/rest/actions/artifacts
+
+GitHub. (n.d.). *REST API endpoints for workflows*. GitHub Docs. Retrieved August 8, 2026, from https://docs.github.com/en/rest/actions/workflows
+
+GitHub. (n.d.). *REST API endpoints for workflow runs*. GitHub Docs. Retrieved August 8, 2026, from https://docs.github.com/en/rest/actions/workflow-runs
+
+National Institute of Standards and Technology. (2022). *Secure software development framework (SSDF) version 1.1: Recommendations for mitigating the risk of software vulnerabilities* (NIST Special Publication 800-218). https://doi.org/10.6028/NIST.SP.800-218

organization_commercial_readiness_fixtures.py

@@ -0,0 +1,128 @@
+"""Test fixtures for the organization commercial-readiness coordinator."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from scripts.ci.organization_commercial_readiness_loop import (
+    GitHubError,
+    PullRequestRecord,
+    RepositorySnapshot,
+    RunRecord,
+    WorkflowRecord,
+)
+
+
+def workflow(
+    *,
+    workflow_id: int = 1,
+    name: str = "Hourly Product Development",
+    path: str = ".github/workflows/hourly-product-development.yml",
+    state: str = "active",
+    content: str | None = None,
+) -> WorkflowRecord:
+    """Build one workflow record."""
+    return WorkflowRecord(workflow_id, name, path, state, f"sha-{workflow_id}", content)
+
+
+def pull(
+    number: int,
+    *,
+    draft: bool = False,
+    base_ref: str = "main",
+    head_sha: str | None = None,
+    updated_at: str = "2026-08-08T00:00:00Z",
+) -> PullRequestRecord:
+    """Build one pull-request record."""
+    return PullRequestRecord(
+        number, draft, base_ref, head_sha or f"{number:040x}", updated_at
+    )
+
+
+def snapshot(
+    repository: str,
+    *,
+    default_branch: str = "main",
+    default_sha: str = "a" * 40,
+    workflows: tuple[WorkflowRecord, ...] = (),
+    runs: tuple[RunRecord, ...] = (),
+    pulls: tuple[PullRequestRecord, ...] = (),
+) -> RepositorySnapshot:
+    """Build one repository snapshot."""
+    return RepositorySnapshot(
+        repository, default_branch, default_sha, workflows, runs, pulls
+    )
+
+
+def repository_payload(name: str) -> dict[str, Any]:
+    """Return one eligible repository response."""
+    return {
+        "full_name": f"ContextualWisdomLab/{name}",
+        "default_branch": "main",
+        "archived": False,
+        "disabled": False,
+        "fork": False,
+        "permissions": {"maintain": True},
+    }
+
+
+def manual_workflow(*, workflow_id: int = 9) -> WorkflowRecord:
+    """Return one safe organization-dispatch product entrypoint."""
+    return workflow(
+        workflow_id=workflow_id,
+        name="Commercial Product Development",
+        path=".github/workflows/commercial-product-development.yml",
+        content=(
+            "# cwl-org-commercial-entrypoint: v1\n"
+            "on:\n  workflow_dispatch:\n"
+            "concurrency:\n  group: product-development\n"
+            "permissions:\n  contents: write\n"
+            "NVIDIA_API_KEY: ${{ secrets.NVIDIA_NIM_API_KEY }}\n"
+        ),
+    )
+
+
+class FakeClient:
+    """Deterministic GitHub boundary."""
+
+    def __init__(
+        self,
+        repositories: list[dict[str, Any]],
+        snapshots: dict[str, list[RepositorySnapshot | Exception]],
+    ) -> None:
+        self.repositories = repositories
+        self.snapshots = snapshots
+        self.dispatched_repairs: list[tuple[str, str]] = []
+        self.dispatched_products: list[tuple[str, int, str]] = []
+
+    def list_repositories(self, organization: str) -> list[dict[str, Any]]:
+        """Return configured repositories."""
+        assert organization == "ContextualWisdomLab"
+        return self.repositories
+
+    def snapshot(self, repository: str, default_branch: str) -> RepositorySnapshot:
+        """Return or raise the next configured snapshot value."""
+        value = self.snapshots[repository].pop(0)
+        if isinstance(value, Exception):
+            raise value
+        assert value.default_branch == default_branch
+        return value
+
+    def dispatch_review_repair(self, repository: str, base_branch: str) -> None:
+        """Record one repair dispatch."""
+        self.dispatched_repairs.append((repository, base_branch))
+
+    def dispatch_product_workflow(
+        self, repository: str, workflow_id: int, default_branch: str
+    ) -> None:
+        """Record one product dispatch."""
+        self.dispatched_products.append((repository, workflow_id, default_branch))
+
+
+class FailingDispatchClient(FakeClient):
+    """Reject review dispatches for failure-path tests."""
+
+    def dispatch_review_repair(self, repository: str, base_branch: str) -> None:
+        """Raise a bounded API failure."""
+        del repository, base_branch
+        raise GitHubError("dispatch rejected")