docs(automation): establish governed control-plane documentation spine

[seonghobae]

Why

Protected main at 6eb06cdd08c79a06f7b390069d4ffa49e2eb7dba had one focused automation document but no discoverable, canonical PRD, TRD, architecture, UML, ERD, security contract, threat model, test strategy, operability contract, incident runbook, traceability map, or durable ADR set.

The audit also found dated prose that contradicted executable behavior: Strix cancellation scope, the code-reviewer tool boundary, central autofix ownership, approval count, external-head support, App-token mutation fallback, and the required-workflow inventory/cadence.

What changed

• Adds a canonical docs/automation/README.md and a complete documentation spine:
  • PRD, TRD, architecture, UML/state/sequence views, conceptual ERD;
  • security contract and exact value-free workflow secret registry;
  • threat model, test strategy, operability contract, incident runbook;
  • documentation coverage assessment and requirement/code/issue/standard traceability.
• Adds eight governed ADRs for writer ownership, revision binding, retries, secrets, independent review, protected-main closure, work conservation, and central/thin-leaf ownership.
• Adds Mermaid diagram-as-code and an editable companion board:
  https://www.figma.com/board/4x8YSMb8teJhU19nDjdkcy
• Links the spine from root maintainer/agent entry points.
• Corrects known code/prose contradictions without changing runtime behavior.
• Adds a machine contract that checks document/ADR completeness, local links, workflow references, Mermaid support, exact secret-name coverage, requirement/threat traceability, and current executable invariants.

Implementation honesty and follow-up

This PR does not describe unmerged or conceptual behavior as protected-main truth. The traceability map separates:

• counted independent non-author approval: [Governance] Establish a counted independent-review path for protected CWL pull requests #772;
• end-to-end dispatch envelope/live-base/review-only binding: fix(actions): bound agent mention dispatch envelope #840;
• subprocess-log redaction hardening: fix(sandbox): redact credential-shaped subprocess evidence #842;
• external-head policy/runtime convergence: [Governance] Align external-head review policy with executable dispatch behavior #889;
• cross-workflow writer lease and fencing: [Reliability] Add a cross-workflow branch writer lease with fencing #890;
• authoritative fail-closed Strix evidence: [Security] Fail closed when Strix produces no authoritative scan evidence #891;
• merge-mode and mutation-credential authority: [Governance] Align scheduler merge modes and mutation credential authority #892;
• recoverable mention invocation claims: [Reliability] Make mention invocation claims recoverable after pre-forward failure #893;
• non-passing terminal scheduler action errors: [Reliability] Propagate scheduler mutation failures to a non-passing workflow result #894.

Validation

• python3 -m unittest tests.test_automation_documentation_contract: 11 passed
• full pytest tests: 988 passed
• owned production coverage: 6978/6978 statements and 2790/2790 branches (100%)
• python3 -m compileall -q scripts tests
• bash -n scripts/ci/*.sh
• git diff --check
• connector comparison: one commit ahead, zero behind, 35 files
• remote tree 555900cbfb824746b30532a89632e09e9dfe576f exactly matches the local commit tree

Runtime impact

Documentation, contract tests, and one stale workflow comment only. No executable workflow or production logic changes.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f0be0baa-cf9c-491a-842e-f72509fd6436

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Closing this Draft as a superseded parallel documentation line, not rejecting its analysis. The broader canonical candidate is #896. Before closure I verified this branch's unique editable FigJam board (4x8YSMb8teJhU19nDjdkcy) exists and inspected its central topology, governance sequence, state machine, and conceptual evidence tables; #896 now links that board explicitly as a supplemental, non-authoritative visualization in its canonical UML. #896 also subsumes this branch's documentation-coverage conclusion through a stricter whole-conversation DOCUMENTATION_AUDIT.md, adds 16 rather than 8 complete ADRs, logical data-model/ERD remediation+continuation+documentation+traceability entities, current standards version discipline, executable operator runbook, controlled maturity states, no-soft-timeout/double-exit semantics, and broader machine contracts.

The #898 branch remains historical evidence and can be reopened if an exact comparison later proves a unique accepted contract was missed. Do not merge both documentation spines.