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 `pages` and commit exactly what’s currently staged. Returns the commit sha.
`propose_pr`	Stage `pages` as a git branch + commit, framed for review, and return that branch.
`stage_best_effort`	Best-effort `stage_paths`: silently no-ops if `root` isn’t a git repo (e.g. `init` run standalone).
`stage_paths`	Git-add `paths` into the index, for a writer to self-stage its own output.
`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 pages and commit exactly what’s currently staged. Returns the commit sha.

pages is added to the index but is no longer a git commit pathspec filter — the commit picks up anything else already staged too (e.g. catalog.jsonl/log.jsonl/ source-manifest.jsonl, self-staged by their writers earlier in the same session, see stage_best_effort), so the state those commands regenerated rides along with the pages that triggered them.

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, branch_prefix: 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.

pages is added to the index but, like commit_pages, is no longer a git commit pathspec filter — the commit picks up exactly what’s staged, pages included, which is how the session’s self-staged catalog.jsonl/log.jsonl/ source-manifest.jsonl writes ride along.

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, in which case this commits whatever else is still staged, if anything.

stage_best_effort ¶

stage_best_effort(root: Path, paths: list[str]) -> None

Best-effort stage_paths: silently no-ops if root isn’t a git repo (e.g. init run standalone).

Writers call this right after writing their own output, so state files ride along in the next commit without a separate call that could fall out of sync (see docs/design/ toolkit-spec.md’s “Write gate”).

stage_paths ¶

stage_paths(root: Path, paths: list[str]) -> None

Git-add paths into the index, for a writer to self-stage its own output.

Called by stage_best_effort right after a writer (write_jsonl, append_log_entry, _stamp_frontmatter, SourceManifest.save) writes its output file(s), so the state files a producer command regenerates ride along in the same commit as the pages that triggered them (see docs/design/toolkit-spec.md’s “Write gate”).

start_wiki_branch ¶

start_wiki_branch(root: Path, frame: str, branch_prefix: 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).