docs: establish authoritative automation control-plane specifications

.github/workflows/automation-documentation-quality-ci.yml

@@ -0,0 +1,74 @@
+name: Automation Documentation Quality CI
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - ".github/workflows/**"
+      - "docs/**"
+      - "*.md"
+      - "scripts/ci/**"
+      - "tests/**"
+      - "requirements-opencode-review-ci-hashes.txt"
+      - "pyproject.toml"
+  push:
+    branches: [main]
+    paths:
+      - ".github/workflows/**"
+      - "docs/**"
+      - "*.md"
+      - "scripts/ci/**"
+      - "tests/**"
+      - "requirements-opencode-review-ci-hashes.txt"
+      - "pyproject.toml"
+
+concurrency:
+  group: automation-documentation-quality-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  PYTHONDONTWRITEBYTECODE: "1"
+
+jobs:
+  docs-quality:
+    name: Full suite and documentation contracts
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout exact event revision
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: requirements-opencode-review-ci-hashes.txt
+
+      - name: Install hash-pinned test dependencies
+        run: >-
+          python -m pip install --disable-pip-version-check
+          --require-hashes
+          -r requirements-opencode-review-ci-hashes.txt
+
+      - name: Run full repository suite with permanent coverage gate
+        run: |
+          python -m coverage erase
+          python -m coverage run -m pytest tests -q
+          python -m coverage report --fail-under=100
+
+      - name: Compile test contracts
+        run: python -m compileall -q tests

.github/workflows/pr-review-merge-scheduler.yml

@@ -553,7 +553,7 @@ jobs:
     # published after the scheduler pass, required merge-preview checks landing
     # late, a base-branch policy blocker clearing) stays approved-but-unmerged
     # with no later trigger. This job re-runs the same trusted scheduler against
-    # every organization repository on an hourly heartbeat so each such PR is
+    # every organization repository on a 15-minute heartbeat so each such PR is
     # merged, branch-updated, or leaves a concrete per-PR blocker reason in this
     # log. It never bypasses policy: all mutations go through the same guarded
     # scheduler contract as the per-repository runs.

.github/workflows/strix.yml

@@ -38,10 +38,10 @@ on:
     # path filters against the PR's full base..head diff, so a PR is skipped only
     # when EVERY changed file is a non-executable doc/image asset; any code,
     # config, build, or workflow change still triggers the scan. Concurrency is
-    # PR-number based for status grouping, but Strix runs intentionally do not
-    # cancel in progress because a pre-job cancellation leaves no scanner log to
-    # review. Queue pressure should be handled by stale-run cleanup outside this
-    # current-head evidence path. For PRs the merge scheduler manages, same-head
+    # event-class/repository/PR-number scoped and cancels obsolete work within
+    # that class. Separate event classes keep a default-branch dispatch from
+    # cancelling the required pull_request_target context. For PRs the merge
+    # scheduler manages, same-head
     # Strix evidence is still forced at merge time via repository_dispatch (which
     # paths-ignore does not affect), so merged code never loses evidence.
     paths-ignore:

AGENTS.md

@@ -2,3 +2,13 @@
 
 <!-- CWL-ENTRY -->
 > **Agents: read the master context FIRST.** Before any work, read [`docs/CWL-MASTER-CONTEXT.md`](docs/CWL-MASTER-CONTEXT.md) (mission · naruon-as-platform + inter-component UML · cross-cutting disciplines · conventions · roadmap · current state), the live **GitHub Project #1** <https://github.com/orgs/ContextualWisdomLab/projects/1> (work/roadmap source of truth), the full spec **ContextualWisdomLab/naruon#974**, and operate the Project per [`docs/agent-github-project-protocol.md`](docs/agent-github-project-protocol.md). The repo/Project — not any private agent memory — is the source of truth.
+
+For central review, security, merge, fix, sandbox, or autonomous-maintenance work,
+also read the authoritative [automation documentation graph](docs/automation/README.md)
+and update its traceability/ADR entries whenever an authority, trust, failure,
+secret, evidence, compatibility, or operational-acceptance boundary changes.
+Treat a prompt or documentation update, Draft/Ready transition, auto-merge or
+review request, defer decision, merge, and status report as intermediate work:
+return to live queue selection in the same invocation. Ordinary termination
+requires two fresh whole-queue no-work sweeps; real budget exhaustion records a
+non-clean `budget_exhausted` continuation handoff.

ARCHITECTURE.md

@@ -0,0 +1,17 @@
+# Architecture index
+
+This repository is both the ContextualWisdomLab organization profile and the
+shared automation control plane.
+
+- The ecosystem and naruon platform context live in
+  [docs/CWL-MASTER-CONTEXT.md](docs/CWL-MASTER-CONTEXT.md).
+- The central automation architecture, product and technical requirements,
+  component/sequence/state/deployment UML, conceptual evidence ERD, trust
+  boundaries, failure domains, operations, and decisions start at
+  [docs/automation/README.md](docs/automation/README.md).
+- Live repository-by-repository governance observations remain in
+  [PR_GOVERNANCE_AUDIT.md](PR_GOVERNANCE_AUDIT.md).
+
+The durable boundary is central shared policy and trusted execution with thin,
+versioned consumers. Product repositories remain independently operable and own
+their domain code, data, tests, releases, deployments, and migrations.

CHANGELOG.md

@@ -8,11 +8,17 @@ Semantic Versioning where the repository publishes a release.
 
 ### Added
 
+- Added an authoritative automation documentation graph covering PRD, TRD,
+  architecture, conceptual ERD, UML behavior views, security and threat model,
+  test strategy, operability, incident response, requirement traceability, sixteen
+  detailed ADRs, current standards doctoring, and machine-checkable index/source
+  contracts.
 - 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.
 
 ### Fixed
 
+- Reconciled superseded autonomous-loop guidance so historical fixed 45-minute/minute-35 cutoffs cannot replace practical-budget plus double-sweep exit proof, and retired the historical `COPILOT_GITHUB_TOKEN` Agent Tasks API alias in favor of purpose-bound GitHub authority separated from `NVIDIA_NIM_API_KEY` model access.
 - Bounded the Strix quality self-test's deterministic timeout fixtures to 3-second process and 5-second fake-sleep budgets so exact-head policy evidence completes inside the existing job limit without changing production Strix scanner timeouts, providers, credentials, or review semantics.
 - Allowed commas and ASCII parentheses in the bounded Strix changed-file path policy so legal tracked Packrat fixtures can receive exact-head security analysis, while rejecting raw `..` components before normalization and keeping controls, backslashes, whitespace ambiguity, and shell punctuation fail-closed.
 - Bound each review-agent invocation key to the wrapper's complete canonical payload, including the base branch and requesting actor; altered fields with a valid-format key now fail before durable-leader election or forwarding, and wrapper write permission is job-scoped.

CLAUDE.md

@@ -21,20 +21,22 @@ This is the ContextualWisdomLab **organization-wide `.github` special repository
    `profile/assets/`. Org-wide defaults `SECURITY.md`, `.github/CODEOWNERS`, and
    `.github/dependabot.yml` also live here.
 2. **Central PR governance and CI hub** — the workflows in `.github/workflows/` are the canonical
-   implementation of PR review, security scanning, and merge automation for **every sibling repo**.
+   implementation of PR review, security scanning, and merge automation for enrolled sibling repos.
    An organization required-workflow ruleset (`CWL Central required workflows`, id `18156473`) runs
    Strix, OpenCode Review, and the PR Review Merge Scheduler from this repo in each target
    repository's context. Repository-local copies of these workflows are drift sources, not
    repo-specific contracts. See `README.md` (policy summary) and `PR_GOVERNANCE_AUDIT.md`
-   (live audit + per-repo DX/UX transfer decisions).
+   (historical snapshot + per-repo DX/UX transfer decisions). Durable current contracts start at
+   [`docs/automation/README.md`](docs/automation/README.md); fetch GitHub live state before acting.
 3. **Infrastructure as code** — `infra/cloudflare/` manages the org's DNS zones and Cloudflare Pages
    hosting declaratively (`zones.json` + `reconcile.sh`, curl + jq only; dry-run by default, writes
    only on explicit manual `mode = apply`).
 
 ## Governance model in one paragraph
 
-**OpenCode judges PRs; GitHub Actions performs mechanical updates and merges.** OpenCode approval is
-evidence-gated (changed files, CodeGraph evidence, Change Flow DAG, test/coverage/docstring evidence,
+**OpenCode, Noema, Strix, and deterministic checks produce separate evidence; GitHub rulesets and
+qualifying reviewers authorize, and GitHub Actions performs guarded mechanical updates and merges.**
+OpenCode approval is evidence-gated (changed files, CodeGraph evidence, Change Flow DAG, test/coverage/docstring evidence,
 an actually-executed PoC via `scripts/ci/sandboxed_verify.py` or `scripts/ci/sandboxed_web_e2e.py`,
 split `Developer experience:` / `User experience:` sections). The scheduler updates a PR branch only
 when the latest review is approved, no current-head check has failed, and GitHub reports the PR as
@@ -57,14 +59,17 @@ Details: `README.md` and `PR_GOVERNANCE_AUDIT.md`.
 - `scripts/ci/` — Python/bash helpers the workflows execute (schedulers, review normalization and
   gates, sandboxed verification, prompt template rendering). `tests/` covers them.
 - `opencode.jsonc` + `ci-review-prompt.md` + `code-reviewer-prompt.md` — the OpenCode reviewer
-  configuration (GitHub Models provider, CodeGraph/DeepWiki/Context7/web-search MCP). All reviewer
+  configuration (NVIDIA NIM first, with a bounded GitHub Models fallback pool and
+  CodeGraph/DeepWiki/Context7/web-search MCP). All reviewer
   agents have `"edit": "deny"`: they are reviewers, never implementers. Keep it that way.
 - `requirements-{bandit,pip-audit,strix,opencode-review}-ci.txt` + `*-hashes.txt` — pinned CI
   dependency sets (see below).
 - `fuzz/` + `.clusterfuzzlite/` — Atheris fuzz targets for the review-output normalizer and the
   ClusterFuzzLite discovery marker.
 - `docs/` — master context, Project protocol, `org-required-workflow-rollout.md`,
-  `scorecard-governance.md`, SBOM inventory.
+  `scorecard-governance.md`, SBOM inventory, and the authoritative
+  [`docs/automation/`](docs/automation/README.md) PRD/TRD/architecture/UML/ERD,
+  security, test, operations, traceability, and ADR graph.
 - `.jules/` — recorded performance (`bolt.md`) and security (`sentinel.md`) learnings from past work
   on `scripts/ci/`; worth scanning before optimizing or hardening those scripts.
 

PR_GOVERNANCE_AUDIT.md

@@ -1,8 +1,32 @@
-# PR Governance Audit
-
-Live check: 2026-06-26 17:53 KST, GitHub API via `gh` as `seonghobae`.
-
-## Canonical Policy
+# PR Governance Audit — historical snapshot
+
+> **Historical evidence, not current authority.** Observed 2026-06-26 17:53
+> KST through the GitHub API. Repository state, rulesets, workflows, providers,
+> review counts, merge modes, and open PRs have changed since this capture.
+> Re-fetch live GitHub state before acting. Durable current contracts start at
+> [`docs/automation/README.md`](docs/automation/README.md); this file preserves
+> the dated fleet observation and decision history for auditability.
+
+> **Current contract correction (2026-08-09).** Strix now uses
+> PR/event-or-ref concurrency with `cancel-in-progress: true`, not a head-SHA
+> non-cancelling group. Protected-main targeted scheduler, OpenCode, and Strix
+> dispatch reject external heads while the contract is resolved in
+> [Issue #889](https://github.com/ContextualWisdomLab/.github/issues/889).
+> The central autofix worker is the shared default for `pg-erd-cloud`; the old
+> repo-local recommendation is superseded. Mutation authority still includes
+> an exchanged repository-scoped App-token fallback after configured tokens.
+> The canonical automation documents and executable source govern.
+
+Snapshot check: 2026-06-26 17:53 KST, GitHub API via `gh` as `seonghobae`.
+
+- Snapshot status: historical and stale for mutation decisions
+- Freshness policy: re-fetch after 24 hours or any relevant repository/ruleset event
+- Regeneration input: live organization repositories, rulesets, PR heads,
+  checks, reviews, threads, workflow sources, and permissions
+- Receipt limitation: the original raw API bundle was not retained; the dated
+  observations below are evidence, not a reproducible current-state digest
+
+## Policy recorded at snapshot time
 
 OpenCode decides; GitHub Actions mutates.
 

README.md

@@ -6,19 +6,28 @@ The public GitHub organization profile lives in [profile/README.md](profile/READ
 
 Homepage: https://contextualwisdomlab.github.io/
 
-PR governance live audit: [PR_GOVERNANCE_AUDIT.md](PR_GOVERNANCE_AUDIT.md).
-The audit includes repository-by-repository DX/UX transfer decisions: what the
-central workflow borrows because it reduces friction, and what it rejects
-because it adds noise or misleading review experience.
+Historical PR-governance snapshot: [PR_GOVERNANCE_AUDIT.md](PR_GOVERNANCE_AUDIT.md).
+It records repository-by-repository DX/UX observations as of its stated date;
+live decisions must re-fetch GitHub state and use the durable contracts below.
+
+The authoritative product, technical, architecture, UML, conceptual ERD,
+security, testing, operability, traceability, and ADR graph for the organization
+automation control plane starts at
+[docs/automation/README.md](docs/automation/README.md). Historical audits and
+rollout ledgers are evidence, while the automation documents define durable
+intended contracts.
 
 ## PR review and merge policy
 
-OpenCode judges PRs; GitHub Actions performs mechanical updates and merges.
-The scheduler updates a same-repository PR branch only when the latest OpenCode
-review is approved, no current-head failed check is present, and GitHub reports
-the PR as behind. After that update, the new head must pass OpenCode, Strix,
-required checks, and review-thread gates again before auto-merge or
-`--match-head-commit` merge can proceed.
+OpenCode, Noema, Strix, and deterministic checks produce separate evidence;
+GitHub rulesets and qualifying reviewers authorize, and GitHub Actions performs
+only guarded mechanical updates and merges. The live organization contract
+requires exactly two approving reviews, dismissal after a push, last-pusher
+protection, resolved threads, and current-head required checks. The scheduler
+updates a same-repository PR branch only when its exact-head evidence and live
+policy allow that mutation. After any update, the new head must pass all review,
+security, required-check, and thread gates again before auto-merge or an
+expected-head direct merge can proceed.
 Branch updates and merges run through the central scheduler mutation credential:
 `PR_REVIEW_MERGE_TOKEN`, `OPENCODE_APPROVE_TOKEN`, the exchanged OpenCode GitHub
 App token, or finally the target workflow token. The scheduler reports the
@@ -78,9 +87,12 @@ push, and commits as `github-actions[bot]` only when a conservative OpenCode
 autofix produces a validated diff. A repository-local autofix worker remains an
 explicit compatibility override through `--autofix-repository`; it is no longer
 the default contract.
-Strix keeps `cancel-in-progress: false` so old evidence is not cancelled by a
-force-push, but PR-scoped concurrency includes the head SHA so an obsolete scan
-does not serialize newer current-head evidence.
+Strix concurrency is scoped by event class, target repository, and PR number (or
+ref for non-PR work), with `cancel-in-progress: true`. A newer event therefore
+cancels obsolete work in its own class, while `repository_dispatch` and
+`pull_request_target` remain separate so default-branch retry evidence cannot
+cancel the required PR context. Only the completed current-head result is
+authoritative.
 
 OpenCode approval is evidence-gated. Before approval, the review summary must
 name changed files, CodeGraph or structural MCP evidence, a Change Flow DAG,
@@ -120,10 +132,11 @@ that discovers runtime matrices, package manifests, test, coverage, docstring,
 E2E, lint, security, Docker, and unpackaged-source gaps before the agent chooses
 commands.
 The configured `code-reviewer` subagent is reviewer-only: it may read, grep,
-glob, and run safe local verification commands, but it must not edit files,
-stage changes, commit, push, install dependencies, mutate branches, or touch
-production state. Blocking findings must be source-backed, severity-labeled,
-impactful, remediable, and include suggested verification.
+and glob, but it cannot invoke Bash, task/subagents, or webfetch under
+`opencode.jsonc`. It must not edit files, stage changes, commit, push, install
+dependencies, mutate branches, or touch production state. Blocking findings
+must be source-backed, severity-labeled, impactful, remediable, and include
+suggested verification for an authorized execution plane.
 
 Failed GitHub Checks are not reviewed as URL lists. OpenCode must explain the
 failed check name, failing step, source-backed file and line when available,