The harness, part by part

Planner

Turns an intent and a slice of tickets into a whole tranche — the milestone, its tasks, and the dependencies between them.

Brief Author

Turns one planned task into one executable brief — the context, the boundary, and the definition of done a task needs before it starts.

Developer

The coding agent that executes a brief — writes the change, opens the pull request, and answers for it.

Reviewer

Judges an open pull request against the brief it came from, and says plainly whether it satisfies it.

Security Reviewer

Checks an open pull request for what a correctness review misses — leaked secrets, unsafe configuration, exposed surfaces.

Archivist

Closes out a merged pull request, recording what shipped and the intent it came from.

Tranche Archivist

Closes out a finished tranche, so the next one starts from what is true now rather than what was true before.

Principal

The person accountable for what merges — the one seat holding authority the mechanism never grants an agent.

Planner → Brief Author

Carries a tranche’s plan down to a single task’s brief, so a task keeps the reasoning that shaped it.

Brief Author → Developer

Carries a brief to the agent that executes it, so nothing the author knew is left implicit.

Developer → Reviewer

Carries finished work to its reviewer already accounted for, so review spends itself on judgement rather than on basics.

Reviewer → Archivist

Carries a review’s actual findings into the permanent record, so a verdict says what was checked, not just that it passed.

Archivist → Tranche Archivist

Carries each task’s close-out record up to the tranche close-out, so a phase can only be called finished once its parts genuinely are.

Tranche Archivist → Planner

Carries a finished tranche’s real outcome to the planning of the next, so no plan is built on a product that no longer exists.

Editing a governed file

Refuses an edit to a governed file until the document that governs it has been read in this session.

git commit

Refuses a commit that does not build or pass its own checks, before the broken state exists at all.

git push

Refuses a push that would land straight on main, on the machine that attempted it.

Guards: publish the branch

Creating a pull request, or editing its title/description

Refuses to open or edit a pull request until it carries everything a reviewer needs to judge it.

Guards: open a pull request, revise a pull request, grant a waiver

Creating a task Issue, or editing its title/description

Refuses to open or edit a task Issue until it carries the full reasoning behind the task.

Guards: create a task issue

Writing to pull requests or Issues through the raw API

Refuses raw API writes to pull requests and Issues, so nothing can edit them behind the gates.

Guards: open a pull request, revise a pull request, grant a waiver

Merging

Refuses a merge while anything the gates check is still failing.

Starting the Dig

Refuses to start work until every precondition for the task is checked live and found clear.

Opening a task PR whose surface includes real code

Refuses a code-carrying pull request whose description no longer matches what it changes.

Opening a task PR

Runs the whole exit check before a pull request is created, so failures surface first.

Spawning a check

Governs which environment variables a spawned check's child process can see, instead of every check inheriting the full parent environment unconditionally.

vinaya check

Resolves core-registered and config-registered checks into one deterministic table before anything runs, instead of letting a config entry run alongside the core check it collides with, unannounced.

publish the branch

Pushing local commits up to GitHub, where the rest of the mechanism can finally see them.

create a task issue

Opening the Issue that a task exists as — its scope, its reasoning and its dependencies, written down before anyone starts.

open a pull request

Proposing finished work for review, carrying the account of what changed and which intent it came from.

revise a pull request

Editing a pull request after it exists — its code, its title or its description, whether or not review already happened.

grant a waiver

Deliberately excusing a rule for one case — an authority the mechanism grants to a person, never to an agent.

commit the work

Recording a change locally — the last moment it costs nothing to catch a mistake.

author the brief

Turning one intent into instructions someone can execute: what to build, what is out of scope, and what done means.

produce the verdict

Judging finished work against the brief it came from, and saying plainly whether it passes.

post the provenance comment

Writing the permanent record of a merged task — what shipped, from what intent, checked by whom.

write the retrospective

Closing out a finished phase of work by recording what actually happened and what it taught.

Brief validation

Re-checks in CI that a pull request’s title and brief sections are properly formed.

Closes linkage

Re-checks that a pull request names the Issue it closes.

Single-plan-PR guard

Re-checks that no two open pull requests are planning the same work at once.

Coherence check

Re-checks every task’s recorded state against what actually merged.

Documentation gate

Re-checks that a change carrying real code also updates the docs explaining it.

Test-plan state

Re-checks that the pull request’s test plan is genuinely ticked.

Typecheck + unit tests

Re-runs the type checker and the unit tests for every package this change can reach.

Conventions

Re-checks formatting and naming against the repo’s own conventions.

AI review

Puts an automated reviewer on every pull request, whatever the hour.

Review gate

Holds the merge until the required review verdicts actually exist.

Implementation exists

Re-checks that every gate the doctrine describes has real code behind it.

No orphan hook/CLI

Re-checks that every hook and CLI in the repo is one the doctrine claims.

No seventh way into GitHub

Re-checks that no route into GitHub exists beyond the ones the doctrine gates.

Cited forge numbers resolve

Re-checks that every Issue and PR number cited in the docs resolves to a real one.

Role/contract integrity

Re-checks that every role and contract the doctrine references is really defined.

reader-resolvable-prose

Re-checks that reader-facing doctrine and site pages don't cite a forge number/tranche slug the reader can't resolve, or use coined vocabulary without defining it.

Post-merge archivist

Records what each merged task shipped, from what intent, and checked by whom.

Coherence oracle, full sweep

Sweeps the whole forge for drift, including work old enough that nobody is watching it.

Docs coherence gate

Checks that every link and reference in the docs still points at something real.

Staleness audits

Flags documentation that has fallen behind the decisions it is meant to follow.

Direct-main-push detection

Catches pushes that reached main anyway, including from writers the hooks cannot reach.

Dead-branch-push audit

Catches commits still landing on a branch whose pull request already resolved.