Design branch publication

[nishu-builder]

Describe branch publication through POST /git/push, caos push-git and publish_source. Define the remote URL, pinned commit, destination branch and required expected head. The endpoint performs one leased create or fast-forward; source policy, import/merge/rebase and reconciliation belong to llm-step.

Clarify Git's refs/heads prefix, the absence of a force-push option, lost acknowledgements and Git's own HTTP retry. Document exact-commit publication and the current .gitignore limitation in agent source capture. PR and stack workflows are added later in #254.

Validation on EC2: Nix build passed. The salted suite passed 46/47 checks in 395s; its Clippy findings were fixed, and Clippy passed on all affected crates with --all-targets -- -D warnings. Formatting passed after those lint-only fixes. HTTPS import/push, shallow-locator/offline-cache, and focused unit checks also passed. The functional suite was not repeated for the lint-only changes.

[nishu-builder]

Layer 1/8. I read the whole stack against this document; the implementation PRs follow it closely, and the places where they diverge are noted on those PRs. Three things I would tighten in the text itself, since it is the contract the others cite:

1. Step 6 lacks a "definitely rejected" outcome. The endpoint's outcomes are converged / conflict / uncertain, but a receiver can answer with a definite refusal (branch protection, read-only token, archived repo) while leaving the branch at E. Under the rules as written that is "uncertain, inspect before continuing", and inspection cannot resolve it because an unchanged branch is not evidence. The implementation in #250 inherits exactly this gap. Adding "a receiver-reported rejection is a conflict with a reason, not an uncertainty" here gives #250 a target.

2. "Concurrent attempts use the same recorded intent" needs to say whether they may all SEND. #252 reads it as observe-only for the non-winning attempt, which produces a wrong Uncertain receipt when the winner's push then lands (details on that PR). Since the push is idempotent under the exact lease, "every attempt that holds the pinned intent may send it" is the safer reading and is what the code comment there already claims.

3. The locator cost change is not mentioned. #249 removes --depth 1 from :@@= resolution so the client never becomes shallow, which means every locator fetch (including the cloud install's --llm-step:@@=github:…) now pulls full history. design/flake-inputs.md still describes single-commit granularity as the point of pinning a commit. Either this document or that one should own the trade-off and the alternative (shallow-fetch into a throwaway repo, copy only the tree closure).

Smaller: the "Interfaces and compatibility" section says the TUI's publication commands are removed, but #247 only removes the TUI layer; the host-side push and gh engine in caos-cli (publication.rs, source_trees::prepare_publication/publish_target, host_git::find_or_open_source_tree_pr_in) is left in place with only its tests calling it. Worth saying here whether that stays as a fallback or is meant to go.

---

Generated by Claude Code