Skip to content
PETROVA

Cosign auto-merge opt-out from the MR-12 control-plane firewall

Date: 2026-07-28 Status: accepted Supersedes: none Superseded-by: none — current

Context

Section titled “Context”

The four registry-edit verbs (petrova_act_registry_edit, petrova_act_reconcile_drift, petrova_act_register_consumer, petrova_act_deregister_consumer) default to human-merge-only under MR-12 — the control-plane firewall. A cosign path already exists in code (cli/src/cosign.ts, cli/src/pr-emitter.ts) and is documented operationally in docs/runbooks/cosign-automerge.md, letting an operator opt a registry-edit PR out of the human-merge default. This weakens the MR-12 firewall, yet no ratifying decision doc backed it — exactly the kind of governance change MR-7/MR-9 require a dated, append-only record for. The documentation audit flagged the runbook as orphaned. This decision retroactively ratifies the mechanism as it ships and records its guardrails.

Upholds: MR-7, MR-9, MR-12.

Decision

Section titled “Decision”

Ratify the cosign opt-out as an authorised, guarded exception to the MR-12 human-merge firewall for registry-edit verbs. Auto-merge is enabled only when three independent gates align:

  1. Caller opt-in — cosign: true (verb option / --cosign on CLI).
  2. Operator master switch — PETROVA_COSIGN_AUTOMERGE=1.
  3. Second principal — PETROVA_COSIGN_TOKEN=<pat>: possession of a distinct second secret, standing in for a second human.

When all three align, the PR is relabelled cosign-automerge (replacing awaiting-human-merge), a Co-Authored-By: <identity> <cosign@petrova.host> trailer is appended so the cosign survives squash-merge into the commit message, and enableAutoMerge(squash) is called. Missing any one gate, behaviour is unchanged: human-merge default holds. The mechanism is an opt-out for high-volume, low-risk batches (e.g. nightly drift reconciliation), not a new default.

Alternatives considered

Section titled “Alternatives considered”
  • Leave the firewall absolute (no opt-out) — human-merge friction on every nightly reconciliation batch outweighs the firewall value at that volume; operators would route around governance instead. Rejected.
  • Single env switch, no second token — a one-secret opt-out collapses the “second principal” property that makes the exception defensible. Rejected in favour of the three-gate design.

Consequences

Section titled “Consequences”

For code:

  • No change. Ratifies the shipped cli/src/cosign.ts + cli/src/pr-emitter.ts behaviour as-is.

For docs:

  • docs/runbooks/cosign-automerge.md is no longer orphaned — this decision is its ratifying record.
  • Referenced from concepts/governance.md as the MR-12 opt-out.

For in-flight phases:

  • None.

For invariants:

  • No MR added or repealed. Records a bounded, gated exception to MR-12; MR-12 itself is unchanged and still the default.

References

Section titled “References”
  • Runbook: docs/runbooks/cosign-automerge.md.
  • Implementation: cli/src/cosign.ts, cli/src/pr-emitter.ts.
  • Firewall rule: core/playbook/META-RULES.md (MR-12).

Sign-off

Section titled “Sign-off”
  • Subagent: docs-governance (session 60f31208)
  • Human: Alex — confirmed 2026-07-28.