Thinking

Readiness and the frozen brief

Read the code before you write, state every code fact as a checked premise, check dispatch readiness, recheck the facts at dispatch, then freeze the brief by its digest. A frozen brief is versioned, never edited.

Readiness step

Premises

Dispatch gates

Frozen brief

Intent

About readiness and the frozen brief

Four steps turn an author's understanding into a frozen Intent:

Step	When	What it guarantees
Readiness step	Before any Issue is written	The author read the code, the docs and the prior decisions, and raised open questions instead of guessing
Checked facts	At the Issue write	Every claim about code is a typed premise the write checks, never prose
Dispatch readiness	Before dispatch, and at first push	The Issue exists, dependencies are merged, no conflicting sibling is open, the render is complete
Frozen brief	At dispatch	The Issue is rendered against the current tree, facts are checked again, and the brief is posted once with its digest. Later changes are new versions

The rule behind all four: an assertion about code, scope, history or a dependency is either a typed fact field, or it is rejected at the write. Prose may explain; it may not claim.

The frozen brief is the Vinaya Intent: the brief digest, plus the objectives version, plus the ruling ordinal (see Overview and the Glossary).

Every guide runs these steps. See Deploy medium work or Deploy backlog issues.

How it works

1
The readiness step
A hard stop before a single task is sized. The Planner states it at the top of the planning pass: "Readiness: I have X, Y, Z; I verified I can read A, B; unresolved: …".
2
Checked facts
Every claim about code goes into ## Premises as a line the write can check.
3
Dispatch readiness
Before vinaya task brief or vinaya task run, four dispatch gates must pass.
4
Recompute and freeze
The brief is rendered, every premise is checked again against the default branch, and the brief is posted as a frozen comment on the Issue.

1. The readiness step

Nine inputs must be confirmed. The step stops when any one fails.

#	Input	Stop when
1	The intent is clear and bounded	It is vague
2	Every project in scope is identified, and its specs, skills and docs are read	A spec exists but cannot be read
3	The code to dig into is readable	A path cannot be read
4	Shared packages can be inspected and their consumers listed	Consumers cannot be listed
5	Relevant prior decisions are known (the decision-record folder is read)	Sources are unreachable, or a record would be reversed without the Principal
6	Every `Project:` resolves in `.vinaya/projects.md`, each row quoted	A name is unregistered
7	Open ambiguities are put to the Principal before planning	—
8	No finished but unarchived prior tranche on a product in scope (except a tranche this plan supersedes)	A prior tranche has zero open Issues and is not archived
9	Every consumed input has a named source: a default-branch path, a `Depends-on` task, or a path and digest the Principal supplied	No source exists

2. Checked facts (premises)

A premise is one line in ## Premises:

`<path>` contains `<text>`

The path is repository-relative and inside the repository. The only predicate is contains.

Form	Checked at Issue write	Checked at dispatch
`<path>` contains `<text>`	Yes, against the author's checkout	Yes, against the head of the default branch
after #<n>: `<path>` contains `<text>` (pairs with `Depends-on: #<n>`)	No: the code does not hold it yet	Yes

The rendered brief lists premises under their own heading, so the Developer reads them as checked facts.

3. Dispatch readiness

Before vinaya task brief or vinaya task run, four dispatch gates must pass:

The Issue exists.
Every depends-on task's pull request is merged to main.
No conflicts-with task has an open pull request.
The render is complete. If not, it names the missing fact.

vinaya task run checks gates 1 to 3 again itself. To run the check on its own and see which condition fails:

vinaya check dispatch-readiness

4. Fact recompute and freeze

Freezing a task runs these steps, in this order:

1
Check the identity
Refuses unless the gh identity is on the Principal allowlist.
2
Render the brief
Renders the brief from the Issue and the tree. Any gap refuses and posts nothing. The render checks every premise again, deferred ones included, against the head of the default branch.
3
Check the body
Runs the same Issue write gate as issue create over the live body.
4
Refuse a second brief
Refuses if a frozen brief already exists, unless --supersede is given.
5
Post
Posts the comment.

The frozen brief

Property	Value
Home	A comment on the task Issue. Never the Issue body, never the pull request body, never a committed file
First version	Marker `<!-- aeg:brief:v1 -->`, then `Brief hash: <sha256>`, then the brief
Digest	The sha256 of the brief text plus a trailing newline
Later versions	Marker `<!-- aeg:brief:v<k> -->` (k = predecessor + 1), `Brief hash: …`, `Supersedes: <predecessor url> — <reason>` on a single line, then the brief
Mutability	Never edited or deleted. A plain second post refuses and names the existing brief
Reader	Every reader uses the newest version authored by a Principal

Changing a frozen brief

A frozen brief is never edited. Each change below makes a new Intent version.

Posts a new aeg:brief:v<k> comment naming its predecessor.

vinaya task brief <tranche> <n> --supersede --reason <text>

For a backlog Issue, use --issue <n> instead of <tranche> <n>.

After freeze, vinaya issue edit refuses any change to the frozen sections (check issue-frozen-brief). The error points to issue objectives edit for objectives. ## Surface, ## Parts and ## Documentation have no self-serve path and go back to the Planner.

Roles

Role	Does
Planner	Runs the readiness step in every lane; writes premises; runs the dispatch act and confirms the render
Principal	Prepares (freezes) a task; any identity not on the Principal allowlist is refused. Edits objectives after freeze. Posts rulings. Performs the readiness step in person for a hot Issue (planned)
Harness	Checks premises at write, checks them again at dispatch, pins the brief by digest
Operator	May run `issue create --validate-only`. Never edits an Issue or widens a Surface

Gates

Gate	Ring and when	Refuses
Premise check	Issue write	A due premise the checkout does not hold
`dispatch-readiness`	Ring 0 at push, Ring 1; `task run`	A missing Issue, an unmerged dependency, an open conflict, a failed rationale
`first-push-dispatch`	Ring 0, at the first push of a task branch	A first push whose dependencies or conflicts are not clear. Same derivation; passes if the forge is unreachable
Fact recompute	At dispatch, inside the render	A premise the default branch no longer holds. The brief does not freeze
`issue-frozen-brief`	Issue edit after freeze	A change to a frozen section
`pr-premise-reassert`	Ring 0 at commit, Ring 1	A `Premise:` pin in the pull request that the repository no longer satisfies

Configuration

Key	Effect
`principals`	Who may freeze a brief, edit objectives and rule
`gateCutovers`	The Issue numbers from which the objectives and brief-section rules apply
`briefSchema.issue.sections`	The builtins the write gate runs at write, and again at freeze
`reviewPolicy`	Its blocking thresholds feed the policy digest bound beside the brief hash

What gets logged

Act	Log events
`task brief`, `task run`, `issue objectives edit`, `pr rule`	`operation` · `completed`
A failing `dispatch-readiness` run	`gate` · `checked`, `gate` · `summary`
The loop starting after freeze	`dev_review_loop` · `loop_started` (Executing)

Every Log event carries input_versions: the brief digest, objectives version, ruling ordinal and policy digest. See Events.

What's next

The loop

What runs once the brief is frozen

Pauses and rulings

How a ruling changes the Intent

Issue kinds

The body each premise lives in

Deploy medium work

Run the whole flow on real work