vibey domain model

Read docs/plans/domain-model.md before touching domain/. This skill is a
compressed orientation; the full spec lives in that doc.

Phases

Six numbered phases plus optional visual interstitial:

INTAKE → ① DESIGN → [optional VISUAL_DESIGN] → ② BUILD ⇄ ③ REVIEW
         ▲──────────────────────────┘               │
                                                     │
③ ── user declines deployment ──────────────────────→ DONE (local)
  │ user opts into deployment
  ▼
④ DEPLOY_DESIGN → ⑤ DEPLOY_EXECUTE → ⑥ DEPLOY_REVIEW → DONE (deployed)

Interactive phases (talk to the user): ①, ③, ④, ⑥, VISUAL_DESIGN.
Autonomous phases (unattended): ②, ⑤.

Loop-backs:

• BUILD → DESIGN when blocked on ambiguity (spec insufficient).
• REVIEW → DESIGN (default) or REVIEW → BUILD (fast path when every
  finding is unambiguous). See ADR-0010.
• DEPLOY_REVIEW can route to ④, ⑤, or back to ①/②/③ depending on the
  failure classification.

Opt-in gates:

• Visual design: after ① accepts a buildable spec, vibey asks whether to
  enter the visual-design interstitial. Declining takes the DESIGN → BUILD
  edge directly.
• Deployment: after ③ has no open product findings, vibey asks whether to
  work on deployment. Declining records completion_mode = "local" and
  transitions to DONE without enqueueing any Azure job.

See ADR-0014 (optional visual-design and deployment opt-in).

Jobs

Job kinds are strings registered against handlers in bootstrap.py (25 kinds
as of 2026-09-15):

• DESIGN: design.interview, design.research, design.synthesize, design.spec
• VISUAL_DESIGN: visual.inventory, visual.plan
• BUILD: build.decompose (alias build.plan), build.implement, build.verify,
  build.integrate
• REVIEW: review.demo, review.collect, review.triage, review.deployment_choice
• DEPLOY_DESIGN: deploy.design, deploy.interview, deploy.synthesize,
  deploy.spec (alias deploy.accept)
• DEPLOY_EXECUTE: deploy.execute (alias deploy.graph)
• DEPLOY_REVIEW: deploy.demo, deploy.triage, deploy.route

docs/plans/phase-protocols.md also names kinds that are not registered
(media.generate.*, visual.review, deploy.discover/plan/validate/apply/
release/verify/recover/collect); treat those as planned. Handoff is not a
job kind: it runs inside the engine-driven job through application/wind_down.py
and application/handoff_orchestration.py.

Job lifecycle (domain/job.py::JobState):
ready → leased → succeeded | failed | awaiting_human | awaiting_capacity | cancelled.

Failure classes (domain/job.py::FailureClass): capacity (opens the
circuit), engine (opens after 3), work (the code is wrong; circuit untouched),
vibey (our bug; circuit untouched).

Bounded ladders park, they do not loop. When build.implement or
build.verify exhausts its effort ladder (or a spend cap), the job parks behind a
human gate. The answer can grant a bound (max_attempts for implement attempts,
max_rounds for verify repair rounds, max_dollars/max_turns for spend);
further attempts run at the ladder's top effort until that grant is used up, then
park again (ADR-0024; granted_limit/granted_amount in
application/build_verify_handler.py).

Idempotency: every job is idempotent under replay via idempotency_key —
a deterministic hash of (project_id, cycle, kind, subject). Re-enqueueing
the same logical work is a no-op. Handlers also guard their own side effects.

Parallel vs serial: some jobs run in parallel (e.g., build.implement —
each work item in its own git worktree). Others are serial (e.g.,
build.integrate — one integration branch, serialised per project and cycle by a
Postgres advisory lock in infrastructure/db/advisory_lock.py, ADR-0029).

See domain/job.py (JobState, FailureClass, backoff(),
idempotency_key()) and the handlers in application/*_handler.py.

Ledger

The append-only event log in Postgres, written in a vendor-neutral schema.
Vendor transcripts (~/.claude/projects/**/*.jsonl, codex rollouts) are
copied in as attachments referenced by events — they are
evidence, not state.

Event kinds (26 total, domain/ledger.py::EventKind): SessionSeeded,
TurnRequested, TurnCompleted, ToolInvoked, TranscriptRecorded, FileEdited,
VerdictRendered,
CapacityRejected, QuestionAsked, AnswerGiven, DecisionRecorded,
AssumptionStated, FindingRaised, FindingResolved, ArtifactProduced,
SavePointCreated, HandoffInitiated, HandoffAccepted, PhaseTransitioned,
BudgetSpent, and the ADR-0014 opt-in gate events VisualDesignOptedIn,
VisualDesignDeclined, VisualDesignAccepted, VisualDesignWaived,
DeploymentOptedIn, DeploymentDeclined.

Readers are forward compatible, writers strict (vibey#275): a stored kind this vibey does not know is read as UnrecognizedEventKind (so LedgerEvent.kind is EventKind | UnrecognizedEventKind), kept in every range, full ledger and digest, skipped by every projection, and never written. Match kinds with is EventKind.X and narrow with isinstance(kind, EventKind) before using a member-only attribute.

Closable events: QuestionAsked, DecisionRecorded, AssumptionStated,
FindingRaised — these are the events the no-loss gate checks.

Digest: every event carries a digest (SHA-256 of canonical JSON payload).
digest_range() computes an order-sensitive Merkle-ish fold of a sequence of
events — this is what R6 (range integrity) checks.

See domain/ledger.py and docs/plans/handoff-protocol.md.

Handoff and the no-loss gate

When an engine hits CreditsExhausted, vibey:

1. Produces a HandoffBrief (the outgoing engine writes it, or the incoming
   engine synthesizes it if the outgoing is dead).
2. Verifies it against the no-loss gate (domain/noloss.py::verify()).
3. If the gate passes, writes the full ledger to
   <worktree>/.vibey/handoff/ledger.jsonl and seeds the next engine.
4. If the gate fails, regenerates (up to 3 attempts), then escalates to
   full_transcript mode, then raises a human gate. In that mode the gate waives
   R1–R5, R7, R9; the design inlines the whole range, but as built the range is only
   the ledger.jsonl file named in the seed prompt — do not describe it as inlined.

The 10 rules (R1–R10):

• R1: remaining-work closure
• R2: open-question closure
• R3: decision closure
• R4: assumption closure
• R5: finding closure
• R6: range integrity (digest match)
• R7: artifact closure
• R8: budget carry
• R9: constraint closure
• R10: containment (nothing in the brief contradicts the spec)

The gate is pure and deterministic — no model call. This is the reason
rotation is safe.

See ADR-0004 (no-loss gate on handoff) and domain/noloss.py.

Rotation

Smooth weighted round robin (nginx-style SWRR), not naive modulo. Engines
are selected from the eligible set via domain/rotation.py::select().

Eligibility: installed, authenticated (doctor passed within TTL),
circuit not open, capability requirements met, and per-phase allow-list
permits it.

When rotation happens: at boundaries only — never mid-turn. Triggers:
new work item starts, capacity rejection (forced, exclude the rejecting
engine), effort escalation, phase transition, operator-requested handoff.

Properties (property-tested):

• No starvation: over sum(effective_weight) consecutive selections, every
  candidate with effective_weight > 0 is selected at least once.
• Weight fidelity: selection counts converge to weight ratios within ±1 over
  any full period.
• Smoothness: no candidate is selected twice consecutively while another with
  effective_weight > 0 has gone unselected longer.
• Determinism: identical candidate state produces an identical selection.

Wiring: application/engine_selector.py::EngineSelector calls select()
for engine-driven BUILD jobs, through SelectingEngineProvider in bootstrap.py.
Candidates come from engine_health rows, so an engine without a recorded
vibey doctor --conformance --record pass is never eligible. A local engine joins
only while its switch is on — gptossloop unless switched off, qwenloop and
claudeloop-local only when switched on — and is preferred first (ADR-0038,
ADR-0064).

See ADR-0005 (smooth weighted round robin), ADR-0007 (rotate at boundaries),
and domain/rotation.py.

Effort ladder

Vibey speaks a normalized 5-level ladder: TRIVIAL, LOW, STANDARD, HIGH, MAX.
Each engine descriptor provides a projection onto native flags, which may
saturate.

Phase base effort:

• ① DESIGN: HIGH
• VISUAL_DESIGN: HIGH
• ② BUILD: LOW (auto-escalating to STANDARD → HIGH after failures)
• ③ REVIEW: HIGH
• ④ DEPLOY_DESIGN: HIGH
• ⑤ DEPLOY_EXECUTE: LOW (auto-escalating)
• ⑥ DEPLOY_REVIEW: HIGH

Phase also carries DEPLOY (a legacy single-phase bridge, base LOW) and
ABANDONED; the phase diagram omits them deliberately.

See ADR-0006 (normalized effort ladder) and domain/effort.py.

Capacity states

Available | WindowExhausted | CreditsExhausted | AuthenticationFailed

The one rule that matters:
CreditsExhausted has no resets_at field and can never acquire one.
This is enforced at three independent layers:

1. Type-level: domain/capacity.py's dataclass has no such attribute.
2. Property-tested: schedule_probe(CreditsExhausted(...)) can only return a
   BackoffProbe, never a DeadlineProbe.
3. Database-level: the engine_health table has a CHECK constraint
   credits_never_have_a_deadline that rejects any INSERT/UPDATE with
   capacity_state = 'CreditsExhausted' and non-null resets_at.

See domain/capacity.py, domain/circuit.py, the constraint in
migrations/0007_engine_health_rotation.sql, and the CLAUDE.md non-negotiable "A
capacity rejection always outranks a completion claim" (it has no ADR of its
own).