docs(automation): establish canonical control-plane architecture baseline

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

@@ -0,0 +1,37 @@
+name: Automation Documentation Quality CI
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/automation/**"
+      - "tests/test_automation_documentation.py"
+      - ".github/workflows/automation-documentation-quality-ci.yml"
+      - "AGENTS.md"
+      - "CLAUDE.md"
+      - "CHANGELOG.md"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: automation-documentation-quality-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation-contract:
+    name: documentation-contract
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - name: Checkout exact source revision
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+      - name: Verify canonical automation documentation
+        shell: bash --noprofile --norc -e -o pipefail {0}
+        run: |
+          test "$(git rev-parse HEAD)" = "${{ github.event.pull_request.head.sha || github.sha }}"
+          python tests/test_automation_documentation.py
+          git diff --exit-code

AGENTS.md

@@ -2,3 +2,5 @@
 
 <!-- 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.
+
+Canonical organization automation/control-plane requirements, architecture, security, operations, diagrams, data model, traceability, and ADRs live in [`docs/automation/README.md`](docs/automation/README.md). Treat document status as evidence scope; `active_pr` is not protected-main implementation.

CHANGELOG.md

@@ -10,6 +10,8 @@ Semantic Versioning where the repository publishes a release.
 
 - 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.
+- Add a canonical automation control-plane PRD/TRD/architecture/security/operations/traceability graph, detailed ADR set, diagram/data-model coverage, and an exact-head documentation fitness workflow.
+- Added a conversation-wide documentation fitness audit, external-orchestration/GitHub-evidence authority split, same-invocation continuation handoff, double-exit termination contract, expanded conceptual ERD/UML views, and ADR-0010 so prompt or documentation updates cannot become report-as-completion while safe queue work remains.
 
 ### Fixed
 

CLAUDE.md

@@ -126,3 +126,7 @@ repeatable compile command.
   cross-repo references as `owner/repo#num` or full URLs; durable knowledge in the repo/Project, not
   private memory; one roadmap phase at a time) are defined in `docs/CWL-MASTER-CONTEXT.md` §7 and
   apply here.
+
+## Automation control plane
+
+Use [`docs/automation/README.md`](docs/automation/README.md) as the canonical graph for organization automation requirements, architecture, security, operations, diagrams, evidence model, traceability, and ADRs. Preserve its implementation-status vocabulary and never promote `active_pr` to shipped behavior.

docs/automation/ARCHITECTURE.md

@@ -0,0 +1,110 @@
+# CWL Automation Control Plane Architecture
+
+Status: active_pr
+
+## Bounded contexts
+
+```mermaid
+flowchart LR
+  X[External orchestration plane] --> O[Organization control plane]
+  O --> Q[Live executable queue]
+  Q --> E[Evidence collectors]
+  E --> R[RCA and feasibility]
+  R --> W[Repository writer lease]
+  W --> P[PR maintenance]
+  W --> D[Product development]
+  P --> G[Gate evaluator]
+  D --> G
+  G --> M[Merge authority]
+  M --> A[Protected-main acceptance]
+  O -. read-only .-> F[Fleet auditor]
+  O --> L[Thin leaf callers]
+  O --> C[Canonical documentation graph]
+```
+
+The External orchestration plane owns scheduled agent invocation, continuation policy, and external writer-lease state. The GitHub execution and evidence plane owns repositories, PRs, branches, workflows, checks, statuses, reviews, rulesets, artifacts, and merge/release evidence. These planes interact but are not interchangeable authorities.
+
+The central repository owns reusable GitHub automation semantics and the canonical documentation graph. Product repositories own product code and thin local caller/contracts. Dedicated repository loops own writes to their repositories; the fleet auditor remains read-only. A conversational decision or automation prompt is an input to reconciliation, not a replacement for repository documentation.
+
+## Plane boundaries
+
+### External orchestration plane
+
+Approved scheduled agent/orchestrator services may hold the authoritative writer lease for a repository and may choose the next execution lane. Their enabled state, schedule, prompt/configuration, and most recent run are external control records. They cannot turn a GitHub check, review, merge, or protected-main runtime result into success by declaration.
+
+### GitHub execution and evidence plane
+
+GitHub-native scheduled/manual/event workflows, reusable workflows, repository-local thin callers, PRs, checks, review threads, artifacts, rulesets, and protected branches are the authoritative source of repository state and execution evidence. Cross-repository reusable behavior belongs centrally unless an accepted architecture decision assigns it elsewhere.
+
+### Canonical documentation plane
+
+`docs/automation/**`, the ADR index, AGENTS/CLAUDE/CHANGELOG links, and their machine-checkable fitness gate are the durable design authority. Pull-request bodies, incident comments, conversation history, and downloadable planning artifacts supply evidence and candidate decisions, but material durable decisions must be reconciled into this graph with explicit maturity.
+
+## Trust boundaries
+
+1. GitHub event and repository metadata are inputs, not proof of current state until refetched.
+2. External automation configuration is lease/control evidence, not source/check/review evidence.
+3. PR-controlled source, comments, logs, and model prompts are untrusted content.
+4. Workflow source is trusted only when immutably identified.
+5. Checks, statuses, formal reviews, model judgments, merge authority, and protected-main runtime evidence are separate channels.
+6. Model credentials are privileged secrets and are not needed for deterministic gates.
+7. A source merge and a protected-main runtime execution are separate acceptance boundaries.
+8. Conversation history and active-PR documentation cannot be presented as protected-main implementation.
+
+## Failure domains
+
+- Repository-local product/test defect.
+- Central reusable-workflow defect.
+- External scheduler/orchestrator continuation defect.
+- Reviewer methodology/provider failure.
+- Runner/network/bootstrap infrastructure failure.
+- Permission/governance configuration.
+- Writer conflict or stale evidence.
+- Documentation authority or traceability drift.
+
+A failure freezes only the smallest affected domain/lane unless evidence proves a broader boundary.
+
+## Control flow
+
+```mermaid
+sequenceDiagram
+  participant X as External Orchestrator
+  participant C as Control Plane
+  participant G as GitHub
+  participant R as Repository
+  participant V as Reviewer/Checks
+  X->>C: Start finite invocation with live continuation policy
+  C->>G: Refetch head, live base, policy, evidence
+  C->>C: RCA + distinct remedies + feasibility
+  alt safe repository mutation
+    C->>R: Exact-head/blob/ref-bound change
+    R->>V: Run exact-head verification
+    V-->>C: Evidence by authority channel
+  else lane blocked
+    C->>C: Defer exact identity and rotate
+  end
+  C->>G: Merge only if real gates pass
+  C->>G: Verify protected-main operation when required
+  C->>C: Continue next executable lane
+  C->>C: Double exit sweep before any terminal response
+  C-->>X: continuation_handoff or bounded termination
+```
+
+## Documentation reconciliation flow
+
+```mermaid
+flowchart TD
+  H[Conversation / prompt / incident / PR evidence] --> R[Refetch protected main and active PRs]
+  R --> K{Canonical documentation line exists?}
+  K -->|yes| U[Update existing canonical line]
+  K -->|no| N[Create one canonical line]
+  U --> S[Assign controlled maturity state]
+  N --> S
+  S --> T[Update PRD/TRD/Architecture/ADR/UML/Data Model/Security/Operations/Traceability as affected]
+  T --> V[Run documentation fitness contract]
+  V --> Q[Return to executable queue]
+```
+
+## Deployment topology
+
+The control plane is hybrid rather than purely GitHub-native. External scheduled agent/orchestrator services provide finite invocation and writer-lease coordination; GitHub provides repository execution, evidence, policy, collaboration, and protected integration; external model/reviewer providers sit behind explicit credential and network boundaries. No durable database is assumed by this architecture; the data model is conceptual unless a persistence implementation is separately accepted.

docs/automation/DATA_MODEL.md

@@ -0,0 +1,67 @@
+# CWL Automation Control Plane — Conceptual Data Model
+
+Status: active_pr
+
+This is a logical evidence/domain model. It does **not** assert that the central control plane currently persists these entities in a database. External scheduler state, GitHub repository state, and canonical documentation state are separate authorities even when one automation run observes all three.
+
+```mermaid
+erDiagram
+  repository_target ||--o{ pull_request_snapshot : contains
+  pull_request_snapshot ||--|| source_revision : identifies
+  pull_request_snapshot ||--|| base_revision : targets
+  pull_request_snapshot ||--o{ check_evidence : has
+  pull_request_snapshot ||--o{ review_evidence : has
+  pull_request_snapshot ||--o{ status_evidence : has
+  pull_request_snapshot ||--o{ workflow_evidence : has
+  pull_request_snapshot ||--o{ dependency_evidence : has
+  automation_run ||--o{ execution_lane : schedules
+  execution_lane ||--o{ deferred_item : defers
+  automation_run ||--o{ incident_hypothesis : evaluates
+  automation_run ||--o{ handoff_record : records
+  automation_run ||--o{ continuation_handoff : continues_with
+  automation_run ||--o{ automation_control_record : observes
+  automation_run ||--o{ operational_acceptance : verifies
+  automation_run ||--o{ secret_requirement : constrains
+  repository_target ||--o{ writer_lease : governed_by
+  automation_control_record ||--o{ writer_lease : may_grant
+  documentation_baseline ||--o{ documentation_fitness_result : evaluated_by
+  documentation_baseline ||--o{ decision_record : contains
+```
+
+## Entities
+
+- `automation_run`: one finite invocation of a maintenance, development, or audit loop.
+- `automation_control_record`: observed external scheduler/orchestrator identity, enabled state, cadence, ownership scope, and configuration revision relevant to a run; it is not GitHub source evidence.
+- `repository_target`: repository identity and control-plane ownership class.
+- `execution_lane`: one independently executable unit such as a PR/head, issue, documentation line, operational acceptance probe, release task, or bounded product slice.
+- `deferred_item`: an exact lane identity temporarily non-actionable because of queued evidence, approval, provider capacity, read-only dependency, writer conflict, or another bounded wait condition.
+- `continuation_handoff`: records the preceding substantive action or defer decision and the next selected executable lane, or the bounded termination reason after the required exit sweeps.
+- `pull_request_snapshot`: current PR metadata captured for a decision.
+- `source_revision`: exact source/head commit identity.
+- `base_revision`: independently resolved current base-ref tip identity.
+- `check_evidence`: named GitHub Check evidence bound to a revision.
+- `status_evidence`: commit-status context, creator, state, target URL where applicable, and revision.
+- `review_evidence`: formal review/reviewer/thread evidence.
+- `workflow_evidence`: workflow/run/job/checkout identity and outcome.
+- `dependency_evidence`: state of a central or stacked prerequisite.
+- `incident_hypothesis`: falsifiable causal hypothesis and disposition.
+- `handoff_record`: read-only transfer to the authoritative owner when mutation is outside the lease.
+- `operational_acceptance`: protected-main consumer execution evidence.
+- `secret_requirement`: purpose, scope, materialization boundary, and least-privilege requirement for a secret.
+- `writer_lease`: authoritative writer scope, source of authority, branch/repository boundary, and conflict evidence.
+- `documentation_baseline`: one canonical documentation authority for a bounded control-plane/product scope.
+- `documentation_fitness_result`: adequacy assessment by artifact class, including missing, stale, partial, adequate, conflicting, or not-applicable findings and required corrective actions.
+- `decision_record`: material decision reconciled from protected-main source, active PRs, incidents, research, or conversation evidence with an explicit maturity state.
+
+## Invariants
+
+- `source_revision` and `base_revision` are never collapsed into one identity.
+- Review, check, status, workflow, model, merge, external-automation, and runtime evidence remain separate authorities.
+- A stale snapshot cannot authorize a write.
+- A `deferred_item` blocks only its exact `execution_lane` unless broader evidence proves shared scope.
+- Every substantive action that does not exhaust the invocation produces a `continuation_handoff` to the next executable lane.
+- A user-visible status or prompt update cannot satisfy `continuation_handoff` by itself.
+- A `documentation_baseline` is singular for its declared scope; conversation or PR-body text does not silently become a second authority.
+- A `documentation_fitness_result` marked missing, stale, partial, or conflicting requires a repository mutation or explicit non-actionable disposition when the current writer owns the documentation line.
+- A conceptual entity is not evidence that persistence exists.
+- Durable database object names, if later introduced, use descriptive two-or-more-word `snake_case` names.