Process model

This page is the compact reference for the 1.0 collaboration model. The normative, full model lives in the repository under docs/spec/process-model.md.

Truth

The open upstream branch is the working truth.
nightly is the integration train; stable is released truth.
A card, event, review, meeting, report or changelog entry is a fact in Git.
BOARD.md, ROADMAP.md and the HTML board are generated views.
Chat steers the work; it is not the record.

Participants

Participant	Authority
Owner	Final human authority: accept ideas and batches, override the roadmap limit, merge and release.
Member	Spark, refine, pitch, review, attend the consortium.
Consortium	The human decision body for pitches, roadmap selection and review.
Agent	One writer: refine, estimate, break down, implement, commit, report, transcribe reviews, remind.

A member may review any batch they do not own. The owner makes the final acceptance decision.

Card kinds and states

Kind	States
`idea`	`spark`, `refine`, `pitch`, `rejected`, `canceled`
`batch`	`accepted`, `roadmap`, `breakdown`, `doing`, `handover`, `completed`, `blocked`, `canceled`
`task`	`pending`, `working`, `done`, `error`, `canceled`

canceled is shared. blocked is batch-only. error is task-only.

Idea machine

spark → refine → pitch → accepted (batch) | rejected
  ↑       ↓         ↓
  └──── spark ← refine
rejected → spark   (explicit human reopen)
spark → canceled

From	To	Action	Human gate
spark	refine	`refine`	human instruction
refine	pitch	`pitch`	creator/member
refine	spark	`park`	creator
pitch	accepted	`accept-idea`	consortium
pitch	rejected	`reject-idea`	consortium
pitch	refine	`request-changes`	consortium
rejected	spark	`reopen`	owner/creator
spark/refine/pitch	canceled	`cancel`	creator/owner

The agent may edit idea content only in refine. It may create a spark on explicit human instruction.

Batch machine

accepted → roadmap → breakdown → doing → handover → completed
    ↑          │         │           │         │
    └──────────┘         └──► roadmap │         └──► doing

From	To	Action	Human gate
accepted	roadmap	`roadmap`	estimate + limit
roadmap	accepted	`unroadmap`	owner/member
roadmap	breakdown	`breakdown`	owner/member; one active batch
breakdown	roadmap	`abort-breakdown`	owner/member
breakdown	doing	`start`	clarification accepted
doing	handover	`handover`	agent; all tasks done
handover	doing	`request-changes`	owner/member
handover	completed	`complete`	owner accept + independent review
any active	blocked	`block`	reason; stores return state
blocked	previous	`unblock`	owner/member
accepted/roadmap/…	canceled	`cancel`	owner/member; cascades tasks

One batch in breakdown or doing; handover can hold multiple batches for review parallelism.

Task machine

pending → working → done
   ↑         │
   └── error ┘
pending → canceled
error   → canceled

From	To	Action	Authority
pending	working	`work`	agent; parent doing, dependencies done
working	done	`done`	agent; commit recorded
working	error	`fail`	agent; reason
error	pending	`recover`	human
pending/error	canceled	`cancel`	human

One task in working at a time. done is immutable; rework is a new task.

Review

Review unit: the batch at handover.
One review artifact per reviewer per round.
Multiple reviewers can work in parallel.
Findings become rework tasks with source_review.
The owner accepts after at least one independent review; an objection can be overridden only with a recorded reason.
Completion requires the report and changelog.

Authority

Action	Agent alone	Agent with human authorisation	Human executes
Spark	no	yes	—
Refine content	only in `refine`	—	yes
Pitch	no	yes	yes
Accept/reject idea	no	yes	yes
Estimate	yes	—	yes
Reestimate	no	yes	yes
Roadmap/unroadmap	no	yes	yes
Breakdown/start	no	yes	yes
Work/done/fail	yes	—	—
Handover	yes	—	—
Request changes	no	yes	yes
Complete	no	yes	yes
Block/unblock	no	yes	yes
Cancel	no	yes	yes
Merge/release	no	no	owner
Override roadmap limit	no	yes	yes

The agent never claims the owner role. It may execute card-level gates after an explicit human decision; branch operations stay human.

Branch rules

stable   ← released
nightly  ← accepted upstream iterations
upstream ← one active iteration

One writer lease.
Merge only downward.
upstream → nightly and nightly → stable are owner-executed.
The agent may prepare the merge check, report and release notes, never merge.

Meetings

Meeting	Cadence	Trigger
Consortium review	Fixed weekly	pitches or roadmap selection
Breakdown clarification	On-demand	open questions in breakdown
Handover review	On-demand	batch enters handover
Release readiness	Fixed cadence	nightly ahead of stable
Recovery/conflict	On-demand	blocked, error or conflict

Pending gates stay visible until accepted, deferred or dismissed. The agent reminds; it does not decide.

Invariants

Exactly one open upstream iteration.
Exactly one writer lease.
One batch in breakdown or doing.
One task working.
Roadmap count ≤ effective limit.
Every roadmap batch has an estimate.
All tasks done before handover.
Independent review and owner accept before completion.
Report and changelog before completion.
No agent self-approval, merge or release.
No deletion; explicit terminal states.
Events append-only.
No hand-edited generated views.

Chat-only trust

Authorisation is recorded as an event with authorised_by and the human statement. It is auditable but not cryptographic. A misbehaving agent with write access could forge it. See Security.

Refusals

The agent must refuse illegal requests and offer alternatives:

Request	Legal alternative
Delete a card	reject, cancel or reopen
Complete without review	handover and review
Merge	owner executes
Edit a pitch	request changes back to refine
Start a second batch	finish, block or cancel the active one
Self-approve	owner accept