vibey-engine 2.0.0__tar.gz

vibey_engine-2.0.0/.agent/rules/vibey-architecture.md

@@ -0,0 +1,270 @@
+# vibey-architecture (Antigravity mirror of `.claude/skills/vibey-architecture/SKILL.md`)
+
+# vibey architecture
+
+Dependencies point inward. `import-linter` enforces this in CI via four
+contracts: onion-layers, domain-independence, application-independence, and
+interfaces-declare-only.
+
+```
+src/vibey/
+├── domain/            # PURE. stdlib only. No I/O, no async, no third-party.
+├── application/       # Protocol ports + use cases. Imports domain + stdlib.
+├── infrastructure/    # Adapters. ONLY layer that may import asyncpg, httpx, etc.
+├── cli/               # Typer. Calls application via bootstrap.
+├── tui/               # Textual. Calls application via bootstrap.
+└── bootstrap.py       # Composition root — the ONE module that sees every layer.
+```
+
+## Where does new code go?
+
+1. **Touches FS, network, clock, database, or an SDK?** → `infrastructure/`,
+   behind a `Protocol` in `application/interfaces/<area>.py` (`azure`, `build`,
+   `design`, `engines`, `gates`, `ledger`, `observability`, `projects`, `queue`,
+   `review`, `system`, `visual`). `application/ports.py` is a compatibility
+   re-export shim of seven names — never add to it. Never `import asyncpg` or
+   vendor SDKs elsewhere.
+2. **Pure decision, zero I/O?** → `domain/`. Examples: `phase.py`,
+   `rotation.py`, `noloss.py`, `circuit.py`, `effort.py`.
+3. **Orchestration (port → domain → port)?** → `application/`.
+4. **Argument parsing / terminal formatting?** → `cli/` or `tui/`.
+5. **Wiring concrete implementations to Protocols?** → `bootstrap.py` ONLY.
+
+When in doubt, push logic inward. `lint-imports` names the broken contract
+when you violate the onion.
+
+## Shape: classes, behind interfaces
+
+Code lives in **class objects**. A module-level function is the method of last
+resort — a package's `__all__` façade, a `__main__` entry point, a bare function
+some library contract requires — and where you use one, write the reason at the
+definition. "It is only a few lines" is not a reason.
+
+**Every class has an interface beside it**, in a mirrored `interfaces/` directory
+(illustrative paths — there is no `services/` package):
+
+```
+src/vibey/services/github_service.py
+src/vibey/services/interfaces/github_service_interface.py
+```
+
+This is the target shape, not the current one. Today's interfaces packages
+(`application/interfaces/`, `cli/interfaces/`, and the empty
+`infrastructure/interfaces/`) are mostly organised by area; `cli/interfaces/early_signals_interface.py`
+is the one module that already follows the `<module>_interface.py` mirror.
+
+The mapping is mechanical: the directory gains an `interfaces/` child, the module
+gains an `_interface` suffix. Interfaces **declare**; they never consume — an
+interface module imports the standard library and other interfaces, nothing else
+from its own tree. The rule applies to every `interfaces/` package; the
+`interfaces-declare-only` contract in `.importlinter` enforces part of it today, for
+`application/interfaces` only (it forbids imports of `vibey.infrastructure`,
+`vibey.cli`, `vibey.tui` and `vibey.bootstrap`).
+
+Why: a class behind an interface is substituted at its seam. The caller takes the
+interface, the test passes a double, and nothing is patched — so the test depends
+on the contract, which is meant to be stable, rather than on the import graph,
+which is not. With a 100% branch floor that is not a style preference: a branch
+reachable only by `monkeypatch.setattr` is a branch whose test breaks for reasons
+unrelated to its subject.
+
+This applies to **new and changed code**. The existing tree (289 module-level
+functions, and 278 module-level classes outside an `interfaces/` package, 277 of
+them with no mirrored `_interface` module — AST walk of `src/vibey/**/*.py`,
+top-level definitions only, measured 2026-09-15) converges module by module,
+and the absorbed subtrees under `src/vibey_runners/` and `src/vibey_tools/`
+converge as they are touched — rewriting them on import would destroy the
+property their import exists to create. `domain/` gets no exemption: a pure
+function becomes a method on a stateless class, and purity is preserved, because
+purity was never about the absence of a class.
+
+See ADR-0016 and sub-doctrine 9.b (the declared seam).
+
+## Dogfood the family first
+
+If a capability exists inside this family, use it. Do not reimplement it, and do
+not reach for a third-party equivalent. The bar is not "is ours better" — it is
+"does ours do this at all".
+
+Between `vibey_bootstrap`'s retry and a retry loop, use theirs. Between its
+dead-letter routing and a hand-rolled failure path, use its. Between its
+correlation scope and threading a request id by hand, use its. When the choice is
+between using a family feature and not using it, **always prefer using it**.
+
+The shape is the one this codebase already uses: a Protocol in
+`application/interfaces/`, an adapter in `infrastructure/` that satisfies it with
+the family package, and a line in `bootstrap.py`. Dogfooding is not a new pattern
+here — it is the existing one, applied to ourselves.
+
+A new implementation of something the family already ships needs a written reason
+at the call site, and the reason must be a capability gap. If ours is missing
+something, the fix is to add it to ours.
+
+Measured 2026-09-15: `src/vibey` imports **zero** family packages. See ADR-0017
+(and sub-doctrine 10.e) for the parity backlog.
+
+## The workspace tenants
+
+This repository is a uv workspace (`[tool.uv.workspace] members =
+["src/vibey_runners/*", "src/vibey_tools/*"]`, ADR-0021). `vibey` is the root
+package; the tenants are absorbed packages that ship inside the one `vibey`
+distribution rather than under their own PyPI names (ADR-0037). Their former
+GitHub repositories (`the-vibey-project/claudeloop`, `vibey-gh`, and the rest)
+and their former PyPI projects no longer exist — never link either; link the
+directory in this repository instead.
+
+| Directory | Package | Python floor | Own checks |
+|---|---|---|---|
+| `src/vibey_runners/claude` | `claudeloop` | 3.12 | pytest, ruff, mypy, import-linter |
+| `src/vibey_runners/codex` | `codexloop` | 3.12 | pytest, ruff, mypy, import-linter |
+| `src/vibey_runners/cursor` | `cursorloop` | 3.12 | pytest, ruff, mypy, import-linter |
+| `src/vibey_runners/agy` | `agyloop` | 3.12 | pytest, ruff, mypy, import-linter |
+| `src/vibey_runners/qwen` | `qwenloop` | 3.12 | pytest, ruff, mypy, import-linter |
+| `src/vibey_runners/common` | `vibey-runners-common` | 3.12 | ruff, mypy, import-linter (no test directory yet) |
+| `src/vibey_tools/gh` | `vibey-gh` | 3.12 | pytest (100% branch), black, isort, mypy, bandit |
+| `src/vibey_tools/skills` | `vibey-skills` | 3.12 | manifest/link validators, unittest |
+| `src/vibey_tools/bootstrap` | `vibey-bootstrap` | 3.12 | pytest (100% line), black, isort, mypy, bandit |
+
+Rules for working inside a tenant:
+
+- **Its own configuration governs it.** Each tenant's `pyproject.toml` carries its
+  own tool sections and test directory (`test/` for `gh` and `bootstrap`, `tests/`
+  for the rest). Run its checks from its own directory; the root `pytest`
+  (`testpaths = ["tests"]`) and the root `mypy`/`bandit`/coverage gates never
+  reach it. Root `ruff check .` and `ruff format --check .` do (`include =
+  ["src/**/*.py", "tests/**/*.py"]`). Absorbed packages keep the gates they
+  arrived with (ADR-0022); see the `vibey-quality-gates` skill for the commands.
+- **Converge as touched.** ADR-0016 and ADR-0017 apply to tenants only as their
+  code is changed. Do not restyle or restructure a tenant on import.
+- **The root layers do not import tenants,** except the dependency-free family
+  packages `domain/` may use (below) and adapters in `infrastructure/`.
+
+## Everything-as-code, and never less of it
+
+If a thing can be declared in the repository and reconciled from it, that is how
+it is done. Branch protection and the repository profile live in `.vibey-gh.toml`
+(`[rulesets]`, `[repository_profile]`) and are reconciled by `vibey-gh`; pipelines
+are rendered from templates; policy is `.importlinter` and the coverage gates. No
+settings page, no one-off `gh api`, no runbook step that says "then set X".
+
+And **everything that can be generic and configurable must be.** A hard-coded
+value that could have been a key, a special case that could have been a rule, a
+path that could have been discovered — each takes a decision away from whoever
+adopts this next, silently. Never change anything to a state that is less generic
+or less configurable. A default is fine; a default is configurability with an
+opinion. A constant is not.
+
+Worked example: `find_root` walked to `.git`, which broke the moment a project
+lived inside a repository belonging to something else. The fix was not an
+explicit root at the two call sites that noticed — it was that a directory
+carrying its own `.vibey-gh.toml` stops the walk. Same work, aimed at the general
+shape. See ADR-0018.
+
+## Convergence-Driven Development is the delivery loop
+
+Every change uses Specification-Driven Development (SDD) for intent and
+acceptance criteria, Test-Driven Development (TDD) for executable checks, and
+Convergence-Driven Development (CDD) above them to ground, implement, test,
+review and repair against the actual tracked repository. At every iteration,
+classify the trajectory as converging, neutral or diverging against the
+remaining criteria and failing checks. A divergence is allowed only when it is
+small, bounded and has a concrete path to reconvergence; large or pathless
+divergence is abandoned. Never treat activity, a marker or a generated file as
+completion evidence. See sub-doctrine 9.c and ADR-0039.
+Project atoms can compose chemical structures, and a suite of suites can be
+alive in the digital realm as a software organism when identity, feedback,
+adaptation, repair and exchange are evidenced; inspect that higher-order
+trajectory whenever the change participates in it.
+
+## A standing rule goes in the canon
+
+This project has law, not just decision records: the constitutional cluster in
+`src/vibey_tools/gh/docs/` — the Constitution, the Twelve Doctrines, the Ten
+Commandments, the Bill of Rights, SD-01 — indexed by `vibey-gh corpus-index` so
+drift between published law and its index is one hash comparison.
+
+The Twelve are **sealed**. Anything new files as a **sub-doctrine** under one of
+them, in the established form, and is ratified by the operator's merge (Article
+II.3). The ratchet applies: a refinement may strengthen, never weaken.
+
+So if what you are writing binds future decisions, survives a rewrite, and is
+about conduct rather than mechanism — it is a sub-doctrine, and writing it only as
+an ADR leaves it with no ratification, no ratchet protection and no chunk in the
+corpus. Write both: the sub-doctrine states the rule, the ADR argues it.
+
+"PostgreSQL, not SQLite" is a mechanism and stays an ADR. "Dogfood the family" is
+a rule and belongs in the canon. See ADR-0020 and sub-doctrine 12.b.
+
+### Filing a sub-doctrine
+
+1. **Pick the parent.** Find the one of the twelve `## N — title` headings in
+   `src/vibey_tools/gh/docs/doctrines.md` the rule stands under. Use the next free
+   letter (existing entries: 2.a–2.b, 4.a, 7.a, 8.a, 9.a–9.b, 10.a–10.e, 12.a–12.c).
+2. **Write it in the established form** — one bold run-in paragraph under the parent
+   heading:
+
+   ```
+   **9.c — short title** *(ratified by the merge that carried this entry)*: the rule,
+   stated as conduct, in present tense.
+   ```
+
+   The ratification note becomes a date only after the fact; do not pre-date it.
+3. **Write the ADR** that argues it and cite the sub-doctrine by number (ADR-0016
+   through ADR-0020 pair with 9.b, 10.e, 12.c, 2.b and 12.b).
+4. **Regenerate and check the corpus index** from the tenant directory:
+
+   ```bash
+   cd src/vibey_tools/gh
+   uv run vibey-gh corpus-index          # rewrites corpus-index.json
+   uv run vibey-gh corpus-index --check  # "corpus intact: N chunk(s)"
+   ```
+
+   The index lives at `src/vibey_tools/gh/corpus-index.json` (32 chunks on
+   2026-09-15); there is no root copy. Commit it with the doctrine change.
+5. **Ratify by human merge.** Article II.3: the doctrines' sub-entries are ratified
+   by humans through reviewed pull requests — a machine may draft, a human
+   ratifies. Article IV.2 (the ratchet): a change may clarify, strengthen or
+   extend; it may never weaken.
+6. **Know the blast radius.** Article V.4: a ratified change to the canon yanks
+   every prior release of the code. A sub-doctrine merge is a release-level event.
+
+A standing subdoctrine carried verbatim in agent files (such as SD-01 in
+`CLAUDE.md`) is amended only by the operator, with a version bump — never edited
+in passing.
+
+## The forbidden imports
+
+`domain/` must never import:
+- Any layer: `vibey.application`, `vibey.infrastructure`, `vibey.cli`, `vibey.tui`
+- Third-party: `asyncpg`, `psycopg`, `httpx`, `typer`, `structlog`, `pydantic`, `textual`
+- `vibey_bootstrap` — named rather than categorised: it carries the Azure SDK and
+  OpenTelemetry, so importing it here pulls a third-party graph in transitively
+- I/O, async and wall-clock from stdlib: `tests/domain/test_domain_purity.py` walks
+  the AST and rejects imports of `asyncio`, `asyncpg`, `subprocess`, `socket` and
+  `pathlib` (plus the third-party names above), calls to `open()`, `os.environ`,
+  `os.getenv`, `datetime.now()`/`today()`, `time.time()`, and any `async def`,
+  `await`, `async with` or `async for`
+
+`domain/` **may** import a family package that is itself dependency-free —
+`vibey_gh`, `vibey_skills`, `vibey_runners.common` all declare `dependencies = []`,
+so they add nothing to the graph that stdlib-only did not already allow. This is the
+ADR-0017 caveat to the stdlib-only rule: a first-party package is not third-party.
+
+`application/` must never import:
+- `vibey.infrastructure`, `vibey.cli`, `vibey.tui`
+
+## Verify before committing
+
+```bash
+uv run lint-imports
+```
+
+If it fails, the error names the contract and the violating import. Fix it by
+moving the offending code to a layer that can legally import the dependency,
+or by abstracting the dependency behind a Protocol in
+`application/interfaces/<area>.py` (`ports.py` is a compatibility re-export shim —
+never add to it).
+
+The onion layering has no ADR of its own: its authority is `.importlinter` and
+`docs/plans/architecture-and-roadmap.md`. ADR-0016 governs the class/interface
+shape; ADR-0021 records the monorepo layout.

vibey_engine-2.0.0/.agent/rules/vibey-domain-model.md

@@ -0,0 +1,215 @@
+# vibey-domain-model (Antigravity mirror of `.claude/skills/vibey-domain-model/SKILL.md`)
+
+# 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, cursor
+bridge logs) 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. qwenloop joins only
+when its feature flag is on, as a standby engine (ADR-0015).
+
+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).