Epic: Unified Write Protection + Single-Config Sync

[padak]

Overview

Unified implementation plan for two interconnected features:

• Single-config sync: pull/push individual configuration by component+config ID #59 Single-config sync: pull/push individual configurations
• Branch protection: enforce write-only-on-branch mode for agents #60 Branch protection: enforce write-only-on-branch for AI agents

These must be designed together because #59 adds new write paths that #60 must gate. A central WriteGuard service enforces branch protection across ALL write operations.

Architecture validated by multi-model consensus

Design reviewed by OpenAI (Codex gpt-5.3), Google (Gemini), and Anthropic (Claude Code opus-4-6). Key consensus points:

1. WriteGuard as single enforcement point -- correct pattern (Policy Enforcement Point)
2. Protection first, then new write paths -- correct delivery order
3. Simplify HMAC to bcrypt-only + marker file -- same security, dramatically less complexity
4. Centralize branch resolution -- one resolve_effective_branch() function replacing 3 duplicated implementations
5. Standalone writes must require explicit --branch -- never default to production for writes
6. WriteGuard is a guardrail, not a jail -- agent with token can always call API directly; document this limitation

Phased delivery

Phase	Scope	Effort	Prereq
0	Write-surface inventory + contract tests	1d	-
1	WriteGuard + bcrypt protection + enforcement in existing write paths	2-3d	Phase 0
2	config pull / config push (standalone + workspace-aware)	4-5d	Phase 1
3	sync pull --config / sync push --config filter mode	2d	Phase 2

Total: 9-11 days

Full design document

See docs/write-guard-and-single-config-plan.md in the repository.

Related

• Single-config sync: pull/push individual configuration by component+config ID #59 Single-config sync
• Branch protection: enforce write-only-on-branch mode for agents #60 Branch protection
• Linear: AI-2851