feat(governance): establish the OpenCoven organization control plane

[BunsDev]

Outcome

Establish OpenCoven/.github as OpenCoven's canonical public organization-governance and portfolio-coordination plane, while preserving repository-local implementation authority and the existing Familiar Contract → Threads → Psyche → Coven authority boundaries.

Tracks #5. Administrative activation remains separately gated by #6. Canonical adoption is tracked by #8, portfolio execution by #9, private federation by #10, and advanced conformance by #2.

What this implements

• a current public repository registry with lifecycle, canonicality, unique domain ownership, risk class, owner/DRI, disposition, manifest-adoption state, and review date;
• three organization ADRs covering the .github decision, governance-metadata authority limits, and public-registry/private-overlay federation;
• machine-readable cross-repository initiatives for governance-plane activation, public portfolio consolidation, familiar identity continuity, and Brand/UI consolidation;
• public dependency, contract, and release-train indexes;
• lifecycle, retirement, exception, evidence, supply-chain, administration/recovery, public/private-data, initiative, and AI-agent change policies;
• JSON Schemas and a dependency-free validator/generator/reconciler;
• deterministic generated portfolio, ownership, initiative, control, and dependency views;
• a root AGENTS.md router and repository agent/manifest.json;
• CODEOWNERS, issue forms, an evidence-focused PR template, and Dependabot configuration;
• least-privilege GitHub Actions with third-party Actions pinned to immutable commits;
• a read-only governance CI gate, reusable agent-readiness and evidence workflows, and scheduled public-inventory drift observation with one deduplicated issue;
• a machine-readable evidence packet for this change.

Security hardening on the current head

The second signed-off commit hardens the reusable and reconciliation boundaries found during pre-handoff self-review:

• the reusable workflow requires a direct caller job pinned to one full 40-character policy SHA;
• the caller's uses SHA, literal with.policy_ref, and runtime input must be identical before policy code executes;
• caller workflow source is resolved beneath .github/workflows/, with traversal, control-character, symlink, and root-escape rejection;
• nested reusable indirection and secrets: inherit are rejected for this contract;
• target repository checkout and policy checkout use persist-credentials: false;
• repository identity comes from the actual GitHub caller, not a caller-selected manifest field;
• public adopters must be present in the public registry;
• manifest validation compares canonical ownership, non-ownership, owner, DRI, ownership status, and risk with the registry;
• R3/R4 manifests require protected paths and canonical bootstrap/fast/full adapter commands;
• evidence validation accepts only contained, regular, non-symlink JSON files under evidence/;
• the drift observer updates only the exact non-PR issue with the expected title, marker, and github-actions[bot] author, and fails closed on duplicate managed issues;
• no OIDC or additional write permission was introduced merely to self-attest workflow identity.

Source-of-truth and authority boundary

This PR centralizes organization-level why / who / ownership / lifecycle / dependency / exit-evidence records. Code, component ADRs, migrations, tests, release evidence, and implementation state stay in their owning repositories. GitHub Projects remains an operational view rather than a second manually maintained authority.

No registry entry, initiative, ADR, issue, Project field, prompt, task, caller field, CI result, or model output may grant itself protected OpenCoven authority. Protected changes still require their canonical authenticated authority and atomic enforcement. Repository content also cannot prove GitHub rulesets, permissions, environments, App scopes, MFA, or break-glass controls are administratively applied; those remain explicit acceptance gates in #6.

Public inventory reconciliation

The source audit observed 44 public repositories on 2026-08-24. The connected GitHub organization exposed 30 public repositories on 2026-09-03. This PR uses the current GitHub inventory as the declarative baseline and retains the older audit as historical planning evidence rather than silently copying stale repository state.

Private repository names and confidential operational context are intentionally omitted. Private work participates through repository-local manifests and access-controlled overlays; the public plane may use only opaque overlay identifiers.

Verification performed

Command / evidence	Result
./scripts/agent-check fast	pass locally and on GitHub
./scripts/agent-check full	pass locally
python3 -m unittest discover -s tests -v	27/27 pass locally; current hardened head passes GitHub Actions
bash -n scripts/agent-bootstrap scripts/agent-check	pass
Python compilation of validator/generator/reconciler and tests	pass
JSON parsing with duplicate-key rejection	pass
YAML parse of issue forms, Dependabot, and workflows	pass
Git tree path/blob integrity against the locally verified package	pass
GitHub Actions on initial head 8a8bc9a123ff87762e5ba8a408f0e51e473aa61c	success, run 33826414214
GitHub Actions on hardened head 3c25c43d30cc7970f3735f103018555e75e09ed6	success
GitHub Actions token scope	read-only contents/metadata for validation; drift issue write remains isolated to the scheduled observer
Organization ruleset/permission effectiveness	not applied by this PR; tracked in #6

Negative tests cover duplicate canonical ownership, public/private leakage, archive/lifecycle mismatch, expired lifecycle reviews and exceptions, unsupported completed initiatives, unregistered workstreams, mutable Action tags, generated-state determinism, public-inventory drift, reusable call-site SHA mismatch, nested indirection, inherited secrets, traversal/symlink/root escape, manifest identity spoofing, R3/R4 protected-path omission, noncanonical agent adapters, and drift-issue spoofing/ambiguity.

Evidence packet: evidence/2026-09-03-organization-governance-plane-v1.json. The PR and its Actions checks provide subsequent remote execution evidence without creating a self-referential evidence-only commit loop.

Migration and rollback

This is additive and reversible. Existing contribution, security, patent, provenance, profile, and Brand/UI audit material is preserved. No repository visibility, archive state, transfer, deletion, release, publication, deployment, merge, or organization setting is changed by this PR.

Before merge, this should receive independent review. Before the governance plane is treated as an administratively enforced write gate, #6 must apply and evidence the required ruleset and organization controls. Pilot consumers must then pin the reusable workflow to the exact accepted .github commit.

Remaining gates

• Remote Governance CI / validate is green on the hardened head and PR merge ref.
• ADRs are ratified through reviewed merge.
• .github/main ruleset and organization/Actions/App/environment/break-glass controls are applied and evidenced under P0 admin gate: protect the governance plane and install least-privilege organization controls #6.
• At least two canonical repositories adopt the manifest and reusable workflow at the exact accepted commit under P0: Pilot canonical agent manifests and immutable readiness workflow adoption #8.
• Current public inventory reconciles after merge without undeclared drift.
• Repository-local consolidation issues execute approved migrations and retirement gates under P0: Execute evidence-gated public portfolio consolidation #9; no destructive action is implied here.
• Private federation is designed and proven without public leakage under P1: Establish access-controlled private governance overlays #10.

[Copilot]

🟡 Changes recommended

The current implementation has a PR-workflow write-permission enforcement gap (security) and schema/validator inconsistencies that can break downstream consumers.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Establishes OpenCoven/.github as the canonical public organization-governance and portfolio-coordination plane by adding machine-readable governance records (registry/initiatives/controls), deterministic validation + generation tooling, and least-privilege GitHub Actions workflows while explicitly preserving protected authority boundaries in implementation repos.

Changes:

• Adds a dependency-free Python governance toolchain (validate/generate/reconcile) plus regression tests for invariants and determinism.
• Introduces authoritative governance records (public repository registry, initiatives, controls, exceptions) and generated derived views.
• Adds organization governance docs/policies/ADRs, evidence-packet schema + example packet, and GitHub community/process scaffolding (templates, CODEOWNERS, workflows, Dependabot).

File summaries

File	Description
tests/test_governance.py	Unit tests for registry/initiative/exception/workflow invariants, deterministic generation, and drift reconciliation.
scripts/governance.py	Thin entrypoint re-exporting the governance API surface and CLI.
scripts/governance_model.py	Core cross-file validation, workflow policy checks, secret scanning, and deterministic generation of derived views.
scripts/governance_core.py	Shared primitives: JSON loading w/ duplicate-key rejection, registry/manifest/initiative/exception validators, secret regexes.
scripts/governance_cli.py	CLI commands plus explicit GitHub API reconciliation and deduplicated drift-issue upsert.
scripts/agent-check	Local fast/full deterministic verification wrapper.
scripts/agent-bootstrap	Bootstrap checks (Python version + required paths) without dependencies/network.
schemas/repository-registry.schema.json	JSON Schema for the public repository registry.
schemas/release-trains.schema.json	JSON Schema for release train index records.
schemas/lifecycle.schema.json	JSON Schema for lifecycle/risk model records.
schemas/initiative.schema.json	JSON Schema for cross-repository initiative records.
schemas/exception.schema.json	JSON Schema for governance exception-set records.
schemas/evidence-packet.schema.json	JSON Schema for governance evidence packets.
schemas/dependencies.schema.json	JSON Schema for dependency-graph records.
schemas/decision-index.schema.json	JSON Schema for ADR index records.
schemas/controls.schema.json	JSON Schema for governance controls records.
schemas/contracts.schema.json	JSON Schema for contract index records.
schemas/agent-manifest.schema.json	JSON Schema for repository agent manifest contract.
README.md	Repository purpose, authority boundary, verification entrypoints, and related work links.
policies/security-and-supply-chain.md	Threat model + baseline controls for governance plane supply-chain risk.
policies/repository-retirement.md	Retirement/consolidation procedure and required evidence expectations.
policies/repository-lifecycle.md	Lifecycle definitions and gates for repository creation/graduation/ownership changes.
policies/public-private-data.md	Public/private data minimization rules and private-overlay federation model.
policies/initiatives-and-decisions.md	Rules for initiatives, statuses, and ADR scoping/immutability.
policies/exceptions.md	Exception/waiver requirements, expiry rules, and authority limits.
policies/evidence-and-verification.md	Evidence hierarchy and rules for reporting verification without overclaiming.
policies/authority-boundaries.md	Explicit separation between governance metadata and protected authority systems.
policies/agent-authored-changes.md	Requirements and prohibited shortcuts for agent-assisted changes.
policies/administration-and-recovery.md	Administration separation-of-duties and recovery evidence expectations.
LICENSE	Adds MIT license.
initiatives/README.md	Initiative record purpose, lifecycle, and required fields.
initiatives/public-portfolio-consolidation-2026.json	P0 initiative to reduce portfolio ambiguity and drive consolidation/retirement gates.
initiatives/organization-governance-plane-v1.json	P0 initiative tracking governance-plane activation and gates (#5/#6/#2).
initiatives/familiar-identity-continuity-v1.json	P0 cross-repo initiative coordinating familiar identity continuity semantics.
initiatives/brand-ui-consolidation.json	P1 initiative for Brand/UI/production authority consolidation boundaries.
governance/repositories.json	Authoritative public repository registry (30 public repos snapshot) with lifecycle/ownership/risk/disposition.
governance/lifecycle.json	Machine-readable lifecycle/canonicality/risk-class model.
governance/exceptions.json	Exception set (currently empty).
governance/controls.json	Governance controls catalog with evidence pointers and stated enforcement mechanism.
generated/portfolio.md	Generated portfolio view derived from the registry.
generated/ownership.md	Generated canonical-domain ownership map derived from the registry.
generated/initiatives.md	Generated initiatives table derived from initiatives JSON.
generated/dependencies.mmd	Generated dependency graph in Mermaid format derived from dependencies index.
generated/controls.md	Generated controls index derived from controls catalog.
evidence/README.md	Guidance for evidence packets and prohibited data in public evidence.
evidence/2026-09-03-organization-governance-plane-v1.json	Machine-readable evidence packet for this governance-plane establishment change.
docs/verification-model.md	Layered verification/adherence model and “no lower layer implies higher layer” guidance.
docs/standards-and-assurance-mapping.md	Non-certification mapping of governance concerns to external frameworks + current gaps.
docs/rollout.md	Reversible rollout plan with explicit gates and sequencing.
docs/operating-model.md	Cross-repo RACI model, authority split, review cadence, and escalation sequence.
docs/github-projects-integration.md	Contract for treating GitHub Projects as derived operational view (not authority).
docs/administration-baseline.md	Checklist for organization/admin settings evidence and reconciliation expectations.
decisions/README.md	ADR directory purpose and immutability/authority boundary note.
decisions/index.json	Machine-readable ADR index for ADR-0001..0003.
decisions/ADR-0003-public-registry-private-federation.md	ADR for public registry + private overlay federation approach.
decisions/ADR-0002-governance-metadata-is-not-protected-authority.md	ADR establishing that governance metadata is not protected authority.
decisions/ADR-0001-organization-governance-plane.md	ADR selecting .github as the public governance plane with activation criteria.
compatibility/release-trains.json	Release train index (trust-stack, product-delivery) with policy notes.
compatibility/dependencies.json	Public dependency edge list with required evidence labels.
compatibility/contracts.json	Contract index with owners and claim rule.
AGENTS.md	Root agent/router instructions capturing repo role, boundaries, and required checks.
agent/manifest.json	This repository’s agent manifest (risk class, protected/generated paths, verification commands).
.gitignore	Ignores Python caches/artifacts and OS metadata.
.github/workflows/reusable-evidence-packet.yml	Reusable workflow to validate an evidence packet against an immutable .github policy ref.
.github/workflows/reusable-agent-readiness.yml	Reusable workflow to validate repo manifest against registry + optionally run repo’s fast gate.
.github/workflows/governance-drift.yml	Scheduled drift observer to reconcile live public GitHub inventory and upsert one issue.
.github/workflows/governance-ci.yml	CI workflow running the deterministic fast gate on PRs/pushes.
.github/PULL_REQUEST_TEMPLATE.md	Evidence-focused PR template aligned with governance-plane requirements.
.github/ISSUE_TEMPLATE/repository-lifecycle.yml	Issue form for lifecycle/retirement/visibility proposals with explicit authorization boundary.
.github/ISSUE_TEMPLATE/governance-initiative.yml	Issue form for cross-repository initiatives with authority boundary acknowledgment.
.github/ISSUE_TEMPLATE/governance-exception.yml	Issue form for governance exceptions with expiry/authority boundary requirements.
.github/ISSUE_TEMPLATE/config.yml	Adds a private security-vulnerability reporting link.
.github/dependabot.yml	Dependabot configuration for GitHub Actions updates.
.github/CODEOWNERS	Bootstrap CODEOWNERS scoping for governance plane paths and workflows.

Review details

Suppressed comments (1)

schemas/repository-registry.schema.json:259

• Same schema/validator mismatch for per-repository disposition: the validator requires disposition.review_by (and CI will fail without it), but the schema doesn’t. Requiring review_by here makes the contract self-consistent for downstream validators.

• Files reviewed: 68/74 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.