Documentation
What Writ is
Git-backed review for prose. Writ tracks a document the way Git tracks code — branches, review, one shared history — but a line diff can't tell you whether a sentence still means what it meant. Writ can: it aligns two versions sentence by sentence and labels every change as wording only or meaning changed, before anyone merges anything.
The loop
Every document lives on main. Nobody writes to main directly — every change happens on its own branch and is proposed as a submission. A submission goes through the same five stages every time:
-
Align
Writ pairs up the sentences in your version with the sentences in the version you branched from — not line by line, sentence by sentence, so a paragraph that was reflowed still lines up correctly.
-
Label
Each paired sentence is labelled wording only (the words moved, the claim didn't) or meaning changed (something the document asserts is now different). A submission is only as serious as its most serious sentence.
-
Gate
A submission where every change is wording only can move fast. In a collaborative document, one that changes meaning follows the document's approval quorum. A solo human author can finish their own meaning change after the checks run; an agent-authored meaning change always needs a different human.
-
Discuss
Along the way, Writ opens threads: a rule finding when your document's own rules (see Rules) catch something, a text conflict when two edits touch the same words, or a disagreement when two edits leave the document asserting two things it can't both say. Every thread is a numbered discussion people and agents can argue in — Writ states what it found, it does not rule on it.
-
Finish
Once nothing is blocked and any applied approval quorum is satisfied, someone allowed by the document's merge policy clicks Finish and the change lands on
main. Writ never merges anything on its own.
What the words mean
Writ's interface avoids Git jargon on purpose — an editorial team should never need to know what a merge request is to use it. A short glossary, since these words recur through the rest of this documentation:
| Word | What it means |
|---|---|
| Document / Tab (experimental) | A document is the shared Git repository; each Markdown path is a tab. Permissions and submissions span the document. Technical APIs retain repo/file names. |
| Submission | A proposed change to a document, open until it's finished or closed. |
| Wording only | Every sentence in the submission still asserts what it asserted before. |
| Meaning changed | At least one sentence now asserts something different. Team documents apply their review policy; solo human documents do not invent a second reviewer. |
| Comment | A numbered thread attached to a document — a question, a note, an open problem. Its later messages are replies; it ends resolved or dismissed. |
| Rule finding | Something your .semgit/rules.yaml caught on a submission. |
| Text conflict | Two edits changed the same words and can't both apply as written. |
| Disagreement | Two edits don't touch the same words, but together commit the document to something it can't say twice. |
| Blocked | An open finding severe enough that the submission can't be finished until it's fixed or waived by a maintainer, with a reason. |
| Waive | A maintainer's deliberate decision to let a submission land despite an open finding. Always requires a reason, always on the record. |
| Finish | Land the submission's change on main. What other tools call "merge". |
| Agent | A principal like any other — a name, a history, a set of permissions — that happens to be operated by software rather than typed at directly by a person. |
Writ aligns, labels, gates, detects and explains. It does not decide, judge, approve, or resolve anything. People choose when a checked change is ready; agent-authored meaning changes always need a named human.
Ready to try it? Continue to Getting started.