[codex] add governed Git promotion

[divo12]

Stack

Depends on #11. Review against codex/durable-heartbeat-scheduler.

Problem

A Fit winner is still an isolated hypothesis. OFW needs an idempotent, reviewable Git package with explicit approval boundaries, durable audit evidence, and a real rollback artifact—without treating a commit or PR as a production deployment.

Implementation

• Adds typed PromotionPolicy modes: report-only, commit, pull request, and explicit deploy.
• Requires a matching approved human ApprovalRecord for direct deploy; rejected, missing, or wrong-fit/winner/policy approvals fail closed.
• Revalidates the content-bound Fit campaign and winner immediately before the first promotion side effect.
• Creates commits in a separate deterministic promotion worktree, preserving the admitted candidate worktree for retry validation.
• Recovers an interrupted worktree/branch and reuses a marker-bound commit instead of creating duplicates.
• Pushes only the deterministic promotion branch to an explicitly named Git remote.
• Provides an idempotent PullRequestPublisher boundary plus a concrete dependency-free gh CLI adapter.
• Provides an optional idempotent deployment adapter; PR mode never invokes it.
• Emits escaped HTML review evidence, typed audit events, a reverse patch, and git revert rollback command.
• Content-binds the result manifest, review report, and reverse patch with SHA-256 digests.
• Persists cancellation before side effects and rejects later execution.
• Extends the heartbeat DAG with a PROMOTE job; no-winner Fit results durably skip it.
• Adds PromotionJobHandler for scheduler workers and typed request resolution.
• Adds a dependency-free ofw campaign status|cancel|resume STORE POLICY JOB_ID CLI that calls the same scheduler service.
• Exposes ofw.promote(...) as the public Python API.

TDD evidence

• A real admitted candidate is committed in a separate worktree, pushed to a bare remote, and represented by one PR.
• Retry after completed result and simulated crash after external PR creation opens no duplicate PR.
• Simulated crash after promotion worktree creation resumes and cleans the same branch/worktree.
• Reverse patch applies cleanly to the candidate content and remains content-bound on cache reads.
• Direct deployment rejects missing and rejected approval, accepts a matching approval, and finds the same external deployment after simulated result loss.
• Durable cancellation creates no promotion ref or commit.
• PROMOTE readiness requires a successful Fit result with progress; no-winner Fit results become SKIPPED.
• CLI status, cancel, and resume round-trip through a serialized immutable automation policy.

Verification

• pytest -q — 149 passed
• Ruff and strict mypy across src and tests — clean
• forbidden construct scan — no Any, raw dict, object, getattr, setattr, lambdas, or __import__
• Bandit — zero findings
• pip-audit — no known dependency vulnerabilities
• source distribution, wheel, and console entry point build successfully

Deliberate scope

• PR creation uses an injected publisher or the installed gh CLI; no GitHub SDK dependency is added.
• Direct deploy remains optional and impossible without an explicit adapter plus matching approval.
• Production rollback remains owned by the deployment system; OFW supplies its reverse artifact and recorded adapter instruction.

---

Summary by cubic

Adds governed Git promotion for Fit winners with approval, audit, and rollback artifacts. Previously winners stopped at analysis; now a PROMOTE job can create a deterministic commit/branch, open a PR via gh, or perform approved direct deploys, and Fit results with no winner are skipped.

• Review notes:

  • New PromotionPolicy modes: none, commit, pull_request, deploy; artifacts include a content-bound report, manifest, and reverse patch; cancellation persists before side effects; commits are created in a separate deterministic worktree and only the promotion branch is pushed to an explicit remote.
  • PR publishing uses a PullRequestPublisher boundary with a GitHubCliPublisher; PR mode never invokes deployments.
  • Direct deploys require a matching human ApprovalRecord; deployments use a DeploymentAdapter and emit a rollback command.
  • Scheduler adds a PROMOTE job and handler; readiness requires a single successful Fit result with progress; no-winner results mark PROMOTE as skipped; StageBudgets adds a promotion budget; a new ofw CLI supports campaign status|cancel|resume; ofw.promote(...) exposes the API.

• Rollout:

  • Update automation policies to include StageBudgets.promotion (required).
  • For PR mode, configure GitRemote and ensure gh is installed and authenticated; set a remote and base branch available to the repo.
  • For deploy mode, implement a DeploymentAdapter and collect a matching ApprovalRecord; without both, promotions fail closed.
  • Use the new ofw console script to query or control campaigns as needed.

^{Written for commit 74a86b6. Summary will update on new commits.}