[Docs] Close residual control-plane documentation gaps after conversation audit #895

Context

A live audit of canonical documentation PR #886 confirms that the control-plane documentation line is now substantially complete and correctly separates the external orchestration plane, GitHub execution/evidence plane, and canonical documentation plane. It also adds ADR-0010 for same-invocation continuation and conversation/prompt/documentation handoff.

This issue records the remaining gaps so they are not lost in chat, prompt text, or PR-body history. It is a follow-up/acceptance ledger, not a competing documentation authority. Extend #886 or its live successor while that line remains canonical.

Exact audit snapshot

Audited #886 at exact head 5f3d8647341a1e626f201dbafe14f515618166a8 on protected base main@6eb06cdd08c79a06f7b390069d4ffa49e2eb7dba.

The branch was actively moving during the audit, so no source/docs write was attempted from this invocation; the branch-level writer lease is intentionally preserved.

Remaining documentation gaps

1. Versioned API / event / schema contract is still absent

The canonical graph has PRD, TRD, Architecture, conceptual Data Model/ERD, UML, Security, Threat Model, Test Strategy, Operability, Incident Runbook, Traceability, Documentation Audit, and ADRs, but no dedicated versioned contract for control-plane events/payloads.

Add a repository-convention equivalent of API_CONTRACT.md / EVENT_CONTRACTS.md / schema registry that covers at minimum:

• repository/issue/pull-request dispatch envelope identity;
• exact source-head and independently resolved live-base binding;
• legacy versus versioned payload compatibility and supersession;
• strict field/type/cardinality rules;
• GitHub repository_dispatch top-level payload constraints and bounded total payload size;
• schema/version negotiation, rejection, replay/idempotency, and migration/rollback;
• explicit maturity state for active PR-only schemas such as the cwl.agent-invocation/v2 work in fix(actions): bound agent mention dispatch envelope #840 rather than presenting them as protected-main behavior.

2. Traceability does not yet map ADR-0010 / continuation authority

At the audited head, TRACEABILITY.md maps ADR-0001 through ADR-0009 families but does not yet map:

• ADR-0010 conversation/prompt/documentation → executable handoff;
• external automation control records versus GitHub-native evidence;
• same-invocation continuation and double exit sweep;
• documentation fitness/reconciliation acceptance evidence.

Add explicit rows and machine-check them.

3. Premature termination and split documentation authority need first-class operational/threat coverage

The documentation audit and ADR-0010 identify these failures, but the canonical Threat Model, Operability, and Incident Runbook should explicitly carry them as first-class failure modes:

• terminal/status response while another safe lane existed;
• prompt or documentation update incorrectly treated as run completion;
• split/parallel documentation authorities for one scope;
• missing continuation_handoff / incomplete exit sweep;
• external writer-lease state going stale relative to repository state.

Define signals, detection, recovery, reopen conditions, and non-bypass constraints.

4. Doctoring / APA 7 reference authority needs a discoverable canonical index

Current canonical docs include primary references, but the control-plane graph should have a discoverable doctoring/reference authority that records current official standards and primary technical references with APA 7 formatting, source date/version where applicable, and decision linkage. Reuse existing docs/doctoring/** conventions rather than duplicating references if an authoritative index already exists.

At minimum cover the standards/authorities materially relied on by the control plane: GitHub Actions/branch protection/rulesets/review/dispatch semantics, NIST SSDF, SLSA, SPDX/SBOM/provenance where applicable, OpenID Connect/OAuth token-exchange boundaries, and relevant secure-software/supply-chain references.

5. Documentation fitness test needs stronger semantic checks

tests/test_automation_documentation.py already checks required files/statuses, index coverage, Mermaid fences, timeless SHA hygiene, live workflow names, and continuation terms. Extend it to require:

• the versioned event/API contract;
• traceability rows for ADR-0010 and external orchestration authority;
• controlled contract/schema version vocabulary;
• Threat Model/Operability/Incident coverage for premature termination and split authority;
• doctoring/reference index discoverability;
• no stale claims in PRD/TRD/traceability when a behavior is only active_pr.

6. Leaf-repository documentation audits remain incomplete by design

DOCUMENTATION_AUDIT.md correctly states that .github must not duplicate product-specific specifications. The conversation contains durable product design families for psychometrics/fast-mlsirm/TEPP, naruon, pg-erd-cloud, BandScope, Inkspan, OriginWeave, EmbedRelay, MHTML ETL Gateway, LifeOS, AppGuardrail, and others.

Each owning repository still needs its own live audit for PRD/TRD/ADR/Architecture/UML/ERD or data model/Security/Threat Model/Test Strategy/Operability/Traceability/doctoring sufficiency under that repository's writer lease. Track/dispatch those audits without creating a second central product-specification authority.

Acceptance

Close only when:

1. docs(automation): establish canonical control-plane architecture baseline #886 or its canonical successor incorporates the central gaps above on one stable exact head;
2. documentation fitness CI proves the strengthened contract on that exact head;
3. every active-PR behavior remains explicitly marked active_pr until protected integration;
4. the PR body/index/ADR count and exact-head verification text are refreshed rather than left stale;
5. leaf-repository audits are either linked to repository-owned tracking items or explicitly dispositioned under their dedicated writer loops;
6. after documentation work, the autonomous loop returns to the live executable queue rather than treating documentation completion as terminal status.

No branch-protection, approval, review, secret, or evidence-authority rule may be weakened to close this issue.