write_gate

The write-gate: every wiki mutation routes through here as a staged PR (see docs/design/idea.md).

CLASS	DESCRIPTION
`ProposePrResult`	Result of staging a wiki change as a local git branch + commit.

FUNCTION	DESCRIPTION
`commit_pages`	Add and commit `pages` onto the currently checked-out branch. Returns the commit sha.
`propose_pr`	Stage `pages` as a git branch + commit, framed for review, and return that branch.
`start_wiki_branch`	Create and check out a new local branch for a wiki-update session, before any pages are committed.

Classes¶

ProposePrResult `dataclass` ¶

ProposePrResult(branch: str, commit_sha: str, frame: Frame, pages: list[str])

Result of staging a wiki change as a local git branch + commit.

Functions:¶

commit_pages ¶

commit_pages(root: Path, pages: list[str], message: str) -> str

Add and commit pages onto the currently checked-out branch. Returns the commit sha.

Used for a batch coordinator’s streaming per-source commits — each one lands immediately on the branch opened by start_wiki_branch, without waiting for the rest of the session’s batches to finish.

propose_pr ¶

propose_pr(root: Path, pages: list[str], frame: str) -> ProposePrResult

Stage pages as a git branch + commit, framed for review, and return that branch.

This is the one write path every wiki mutation is meant to route through (see docs/design/idea.md’s “write gate” decision). v1 stops at the local branch + commit: it never pushes to a remote or opens a real GitHub PR.

If the current branch was already opened by start_wiki_branch (a batch coordinator’s session branch), this reuses it instead of creating a new one, and tolerates pages having nothing left to commit — every page may already have landed via that session’s streaming commit_pages calls.

start_wiki_branch ¶

start_wiki_branch(root: Path, frame: str) -> str

Create and check out a new local branch for a wiki-update session, before any pages are committed.

A batch coordinator calls this once, before dispatching any subagents, so every per-source commit_pages call and the session’s closing propose_pr call land on the same branch (see docs/design/tickets — coordinator mechanism for batch dispatch).