The harness, part by part

Planner

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

Architect

Declares a product goal as a Milestone, and names which tranches serve it — nothing else.

Developer

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

Operator

Runs one already-planned task through the existing controller — starts it, reads its grounded status, reads why its pull request is red, presents the persisted escalation, and asks for authenticated continuation or cancellation. Never plans, codes, rules, approves, or merges.

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 → Developer

Carries a brief to the agent that executes it, so nothing the plan 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.

Security → Archivist

Carries the security review's verdict and findings into the permanent record, so a recorded pass is a copied fact, not a claim.

Architect → Planner

Carries a product goal's declared tranche intents down to the Planner, so a tranche's goal is derived rather than invented.

Principal → Operator

Carries process authority down and content decisions up — the Principal tells the Operator which planned task to run, pause, or stop; the Operator brings the Principal the escalations only the Principal may rule.

Planner → Operator

The Operator runs what the Planner cut — the Planner makes a task dispatchable, the Operator operates it, and every scope or strategy change routes back to the Planner, never through the Operator.

Editing a governed file

Couples an edit to a governed code surface to its owning document, so the two cannot drift apart in one change.

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

Merging

Holds the merge on the forge side while anything the gates check is still failing.

Starting the Planner's dispatch act

Refuses to start work until every precondition for the task is checked live and found clear. Optionally (task 10, `PREMISE_FILE=<brief.md> vinaya check dispatch-readiness`), also re-asserts a local brief's `Premise:` pins against current on-disk state and fails on any pin that no longer holds.

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.

Pushing a task branch that matches no planned task

Refuses to push a task branch whose name matches no task row derived from the forge.

Pushing to a branch whose pull request already resolved

Refuses a push to a task branch whose most recent pull request is already merged or closed.

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

A task branch's first push

Re-runs the dispatch-readiness gate once, on a task branch's first push, before its pull request exists.

A task branch's first push

Assigns the task's Issue to the authenticated pusher on the branch's genuinely first push — visibility automation, deliberately not a gate.

Committing or pushing while checked out on the default branch

Refuses a commit or push whose current branch IS the repo's default branch — mechanizing the worktree-plus-PR rule at ring 0 for every adopter, not just this repository's own hand-written pre-push script (the `git push` row above, `repo-own`, predates this check and covers a different class: a push whose destination *ref* is the default branch, not a local checkout parked on it). Registered in `coreCheckRegistry()` (task 9), so `vinaya init` ships it to every adopter through the generated `check --all --local` hooks — closing the gap where this rule previously reached only this repo's own maintainers.

Committing when the token-metering adapter is wired but unreachable

Refuses a commit when the token-metering probe finds a wiring point resolved — a transcript pointer naming a path — but cannot reach what it names. A host never wired to meter at all still passes unchanged.

Committing a check bin that nobody can execute

Refuses a staged executable whose index mode is not `100755`, on the machine that staged it.

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

Dispatching one intent as 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.

create the milestone

Declaring a product goal as a Milestone — free-text title, prose goal, an optional Release: field as the version's sole authority, and an optional list of which tranches serve it.

Brief validation

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

PR-report density

Re-checks that a pull request's `## Summary` and `## Scope` sections are each exactly one paragraph, per the canonical PR-body form.

Closes linkage

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

Writing to pull requests or Issues through the raw API

Re-checks, in CI, that whatever landed on a pull request or Issue satisfies the CLI's validated-write shape rules — the actual backstop against a raw write, since no ring-0 hook can refuse one at the point it happens.

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 `[principal]` test-plan boxes are genuinely ticked.

Principal Test Plan wait

Owns the merge condition an unticked `[principal]` Test Plan item represents, as its own independent check — the Principal wants every merge condition to be its own check, so that all green means mergeable, rather than a reviewer having to notice this reason buried among `review-gate`'s own several possible failures.

Typecheck + unit tests

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

Conventions

States where formatting/naming conventions stand in this repo: currently unenforced.

AI review

Requires independent review verdicts to exist on every pull request before merge.

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, and that a row scaffolded to fix that stays visibly incomplete until a human finishes it.

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.

Doctrine-registry parity

Re-checks that every row this page marks `product` actually ships as a real, adopter-runnable check, not just a documented claim.

reader-resolvable-prose

Re-checks reader-facing doctrine, durable specs and configured source comments for unresolvable citations and coined vocabulary.

retired-vocabulary

Re-checks that no doctrine page claims a retired mechanism is still live.

doctrine-portability

Re-checks that shipped doctrine doesn't cite a path that exists only in the authoring repository.

doctrine-no-procedures

Re-checks that doctrine (`roles/*.md`, `contracts/*.md`, …) describes commands rather than scripting them (task 9/task 10's rule).

No new on-disk state

Blocks a diff that creates a new on-disk state file duplicating what the forge already derives.

workspace-escape

Re-checks that no source file's constructed filesystem reference reaches outside its own workspace package, or points at a path that does not exist.

changeset-coverage

Re-checks that a diff touching a published package's own shipped files also carries a changeset in the same diff.

quoted-command

Re-checks that a doc's explicitly marked quote of a command or config line still matches, verbatim, the file it names as its source.

Bare code-fact digits in a PR body

Re-checks that a pull request's narrative prose carries no bare `<path>.<ext>:<digits>` code-fact pointer outside a fenced code span or a `Premise:` pin.

Evidence-block freshness

Re-checks that a PR's Evidence block still matches a fresh recompute at the PR's current head.

Documentation gate

Re-checks C5 doc-coverage — the SAME code→doc binding the push-time row above enforces — again at PR create/edit time, not only on push.

Surface-scope

Re-checks that a task branch's changed files stay inside its own Issue's declared `## Surface` — never inside a declared `out:` glob.

PR-body premise reassertion

Re-checks, in CI, that a pull request body's `Premise:` pins still hold against the PR's own current tree — not only at Step 0, authoring time.

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.

Token self-report

Collects a role's exact token usage on **one** host, by reading that host's own session transcript, and emits the line the PR-body token report is built from. The obligation to report tokens is host-agnostic doctrine; this row is only the adapter that satisfies its collection step on today's shipped reference host, never the requirement itself — an adopter on another harness collects by their own means and ships no equivalent of this row.

Published lifecycle audit

Runs the full shipped-command lifecycle against the real published `@attalabs/vinaya` npm artifact — never this workspace's own source.