Org Rollout & Governance Audit Log (P2-24)

This page documents the multi-repo / monorepo / org rollout command and the governance audit log substrate it shares with adapter governance (P2-26).

Governance audit log (cortexbuild_core.audit)

A new append-only audit/event log records governance events across repos: adopt, override, sync, promotion, upgrade, rollout. It lives at .cortexbuild/audit-log.yaml (one per repo).

It is an additive ledger — not the recurrence ledger

The P2-24 ticket refers to "the recurrence ledger" for rollout/governance events. That wording is interpreted as this audit ledger, a structurally separate surface. The audit log:

• Does not reuse or mutate the recurrence ledger (cortexbuild_core.ledger), whose add raises on duplicate ids and whose entries are recurrence-classes, not events.
• Does not reroute the missing-context overrides log (.cortexbuild/context/missing-context-overrides.yaml, cortexbuild_core.context.gate). That log keeps its own schema; rollout/adopt emit additional audit events, they never replace override records.

Guarantees

Concern	Guarantee
Concurrency (B2)	Writes take a portable advisory lock (atomic O_CREAT \| O_EXCL lockfile — no new mandatory core dependency). Parallel writers never lose/corrupt entries. A stale lock from a crashed holder is reclaimed after a timeout.
Idempotency (B2)	Events dedupe by content_hash (computed over the semantic fields, excluding the ordinal). Re-running an action is a no-op that never raises (unlike the recurrence ledger).
No PII / byte-stable (S7)	Ordering is a deterministic ordinal (never wall-clock) plus an optional commit anchor; target is a canonical slug/namespace (IdentityExtractor); free-text (detail) is routed through redact_for_egress.
Backward-tolerant	Unknown keys are ignored on load; older/newer files still parse.

cortexbuild rollout

Runs the CortexBuild passes across a list/glob of repos and emits a single deterministic aggregate report.

# Dry-run (read-only conformance only) across child repos of ./org
cortexbuild rollout --base ./org

# Apply the mutating passes (adopt + standards sync) to selected repos
cortexbuild rollout --base ./org --glob 'team-*' --apply --json

Safety contract

• S2 — partial-failure isolation + transactional. Each target is isolated; a failure is caught, marked failed with a redacted reason, and the batch continues. Read-only (conformance) is separated from mutating (adopt/sync); mutation is dry-run by default and requires --apply. Before mutating, the target's .cortexbuild/ governance state is snapshotted and restored on failure, so each target is all-or-nothing and a half-migrated org can never happen.
• S3 — enumeration safety. Explicit list / glob with nested-.git / node_modules / .venv exclusion (reusing the structural analyser ignore set), a symlink-loop guard, and a --max-repos bound.
• S4 — monorepo-aware. Reuses _detect_top_level_services / MONOREPO_PARENT_DIRS: a service is a manifest-bearing top-level dir; when sub-services are detected the repo root is excluded (no double-count).
• S1 — determinism / no-egress. Repo identity is the canonical slug / namespace; every path / free-text is routed through relpath + redact_for_egress; no wall-clock is recorded; the engine is fully offline. The aggregate bytes are identical for structurally-identical orgs.
• B2 — audit. A rollout event is emitted to each repo's audit log.