claudeloop 0.2.0__tar.gz

claudeloop-0.2.0/.claude/settings.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Agent(*)",
+      "Artifact(*)",
+      "Bash(*)",
+      "Cd(*)",
+      "Edit(*)",
+      "EnterWorktree(*)",
+      "ExitPlanMode(*)",
+      "Glob(*)",
+      "Grep(*)",
+      "KillShell(*)",
+      "LSP(*)",
+      "Monitor(*)",
+      "MultiEdit(*)",
+      "NotebookEdit(*)",
+      "PowerShell(*)",
+      "Read(*)",
+      "ShareOnboardingGuide(*)",
+      "Skill(*)",
+      "TaskCreate(*)",
+      "TaskGet(*)",
+      "TaskList(*)",
+      "TaskOutput(*)",
+      "TaskStop(*)",
+      "TaskUpdate(*)",
+      "TodoWrite(*)",
+      "ToolSearch(*)",
+      "WebFetch(*)",
+      "WebSearch(*)",
+      "Workflow(*)",
+      "Write(*)"
+    ]
+  }
+}

claudeloop-0.2.0/.claude/skills/claudeloop-agent-sdk/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: claudeloop-agent-sdk
+description: Explains how claudeloop integrates with claude-agent-sdk (ClaudeAgentOptions, ClaudeSDKClient vs query(), RateLimitEvent, ResultMessage, AssistantMessage, session discovery via list_sessions()) and the never-block-on-a-human design (permission_mode, can_use_tool, AskUserQuestion handling, hooks). Use this whenever building or modifying src/claudeloop/infrastructure/agent/ (the M2+ agent gateway, options builder, message translation, session catalog, capacity probe), whenever the user asks about the Claude Agent SDK, ClaudeAgentOptions fields, session resumption, rate-limit events, or why a run might block on a human. Make sure to consult this before writing any code that calls claude_agent_sdk directly — infrastructure/agent/ is the ONLY place that import is allowed, per the onion architecture (see the claudeloop-architecture skill), and getting the never-block guarantees wrong here defeats the entire purpose of this project.
+allowed-tools: Read Grep Glob
+---
+
+# claudeloop + claude-agent-sdk integration
+
+`infrastructure/agent/` is the only place `claude_agent_sdk`
+may be imported — see the `claudeloop-architecture` skill for the enforced
+onion rule. This skill covers the SDK integration specifics; consult
+`claudeloop-domain-model` for how the resulting signals get classified.
+
+## `ClaudeSDKClient` over `query()` — this is not optional
+
+`query()` (single-shot) raises a **plain `Exception`** after yielding an
+error `ResultMessage`, and the underlying process exits non-zero. A
+streaming-input `ClaudeSDKClient` **stays alive** across error results — you
+can keep sending messages on one live process with no resume/respawn. The
+`AgentGateway` adapter (infrastructure/agent/gateway.py::ClaudeAgentGateway) MUST use `ClaudeSDKClient`, not `query()`, or
+the whole point of collapsing the legacy respawn loop is lost. See ADR 0002
+for the full reasoning.
+
+## Key `ClaudeAgentOptions` fields for this project
+
+- **`permission_mode="bypassPermissions"`** — required for autonomy. Note:
+  the Python SDK has **no `dangerously_skip_permissions` field**; this is
+  its equivalent. Do not go looking for a field that doesn't exist.
+- **`can_use_tool`** — a defensive callback that must NEVER await input.
+  Intercepts `AskUserQuestion` specifically and **denies with guidance**
+  (not auto-answers) — see the "Never blocking" section below.
+- **`output_format`** — a JSON schema
+  (`{complete: bool, remaining_work: [str], blocked_on: str|null, summary:
+  str}`) so each turn returns a `ResultMessage.structured_output` the
+  domain layer's `completion.py` can evaluate directly, rather than
+  substring-matching output text.
+- **`resume` / `continue_conversation` / `fork_session` / `session_id`** —
+  `session_id` cannot combine with `resume`/`continue_conversation` unless
+  `fork_session=True` is also set. Get this wrong and session resumption
+  breaks in a way that's easy to miss in a quick test.
+- **`setting_sources=None`** for the throwaway capacity probe specifically
+  — no `CLAUDE.md` should load for a one-token "are we still limited"
+  check.
+- **`hooks`** — `PermissionRequest` auto-allows; `Notification` logs only,
+  never blocks.
+
+## Never blocking on a human — every mitigation, concretely
+
+| Stall path | Mitigation |
+|---|---|
+| Permission prompts | `permission_mode="bypassPermissions"` |
+| Unexpected permission path | Defensive `can_use_tool` returning `PermissionResultAllow` without ever awaiting input |
+| `AskUserQuestion` | Intercepted, **denied with guidance** — e.g. "running autonomously, no user available — choose the option you would recommend, note the assumption, and proceed." NEVER fabricate an answer; that silently invents a decision nobody made. |
+| `ExitPlanMode` | Auto-approved |
+| `Notification` hooks | Logged, never awaited |
+| Model asks "Shall I proceed?" in plain text | No tool call to intercept — mitigated via an appended system-prompt fragment establishing autonomous operation |
+| TTY-dependent stdin | Never inherit a TTY — must be safe under `nohup`/systemd |
+| MCP OAuth | Genuinely cannot complete unattended — the `doctor` command checks configured MCP servers up front and fails fast, naming them, rather than discovering the problem mid-run |
+
+If you're adding a new tool-interception path, apply the same test every
+time: **can this ever wait on stdin or a human response?** If yes, it needs
+an explicit mitigation in this table before it ships.
+
+## Rate-limit signals — read three, trust none alone
+
+`RateLimitEvent.rate_limit_info`: `status` (`allowed`/`allowed_warning`/
+`rejected`), `resets_at`, `rate_limit_type`
+(`five_hour`/`seven_day`/`seven_day_opus`/`seven_day_sonnet`/`overage`),
+`utilization`, `overage_status`, `overage_resets_at`,
+`overage_disabled_reason`. The Claude Code binary contains the string
+`[sdkMessageAdapter] Ignoring rate_limit_event message` — treat this event
+as possibly absent and always corroborate with `ResultMessage
+.api_error_status` and `AssistantMessage.error` (see the
+`claudeloop-domain-model` skill's `TurnSignals` section for exactly how
+these three combine).
+
+## Session discovery — use the supported API
+
+`list_sessions()` / `get_session_info()` return `SDKSessionInfo` (session_id,
+summary, last_modified, custom_title, first_prompt, git_branch, cwd, tag,
+created_at) via cheap stat + head/tail reads. **Never** hand-parse
+`~/.claude/projects/<encoded-cwd>/*.jsonl` directly — the docs explicitly
+warn the transcript format changes between Claude Code releases, and this
+API exists specifically to replace that fragile approach from the legacy
+script.
+
+## The capacity probe — deliberately minimal
+
+The throwaway turn used while `WAITING` (see `claudeloop-domain-model`):
+one-token prompt, `max_turns=1`, no tools, `setting_sources=None`, and
+`extra_args={"no-session-persistence": None}` so it leaves no transcript
+and doesn't pollute the working session's history with "OK" turns. A
+rejected probe isn't billed by the API.
+
+## `CLAUDE_CODE_RETRY_WATCHDOG` — deliberately off by default
+
+Do not set this env var in the default agent gateway configuration. It
+retries 429/529 in-process indefinitely with no progress reporting, no
+credits-vs-window discrimination, and no `--max-wait`. It's exposed as an
+explicit opt-in flag (`--retry-watchdog`), never the default. See ADR 0005
+for the full reasoning if you're tempted to "simplify" by using it instead
+of the probe-based waiting policy.
+
+## Full reference
+
+`docs/architecture/decisions/0002-agent-sdk-over-subprocess.md`,
+`docs/architecture/decisions/0005-retry-watchdog-off-by-default.md`,
+`docs/architecture/decisions/0007-ask-user-question-denied-with-guidance.md`,
+`docs/guides/never-blocking.md`, `docs/guides/rate-limits-and-credits.md`.

claudeloop-0.2.0/.claude/skills/claudeloop-architecture/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: claudeloop-architecture
+description: Explains claudeloop's onion architecture — the four layers (domain, application, infrastructure, cli), the import-linter contract enforcing them, and exactly where new code belongs. Use this whenever adding a new file, class, or function to src/claudeloop/, whenever unsure which layer something belongs in, whenever import-linter or lint-imports fails, or when the user mentions "onion architecture", "layers", "ports and adapters", "bootstrap.py", "composition root", or asks "where should this go". Make sure to consult this before writing any new module under src/claudeloop/ — placing code in the wrong layer is the most common mistake in this codebase and import-linter will reject it in CI regardless.
+allowed-tools: Read Grep Glob Bash(lint-imports)
+---
+
+# claudeloop architecture
+
+`claudeloop` is a strict onion / ports-and-adapters design. Dependencies
+point inward only. This is enforced in CI and pre-commit by `import-linter`,
+not by convention — a violation fails with a named contract error, not a
+review comment.
+
+## The four layers, innermost first
+
+```
+src/claudeloop/
+├── domain/           # PURE. stdlib only. No I/O, no async, no third-party imports.
+├── application/       # Protocol-based ports + use cases. Imports domain + stdlib only.
+├── infrastructure/    # Adapters. The ONLY layer allowed to import anthropic /
+│                       #   claude_agent_sdk / structlog / httpx / any third-party SDK.
+├── cli/                # Typer commands. Calls application use cases via bootstrap.
+└── bootstrap.py         # Composition root — the ONE module allowed to see every layer.
+```
+
+## The decision test — where does new code go?
+
+Ask in this order:
+
+1. **Does it touch the filesystem, network, clock, or an SDK?**
+   → `infrastructure/`, behind a `Protocol` port defined in
+   `application/ports.py`. Never call `anthropic.*` or `claude_agent_sdk.*`
+   from anywhere else.
+
+2. **Is it a decision — a branch determining what happens next — with zero
+   I/O of its own?**
+   → `domain/`. Test: can you write its test as
+   `assert some_function(SomeDataclass(...)) == ExpectedResult(...)` with no
+   mocking, no fixtures beyond dataclass literals? If yes, it's domain.
+   Existing examples: `domain/classify.py` (turn signals → capacity state),
+   `domain/waiting.py` (capacity state → next probe instant),
+   `domain/completion.py` (structured output → completion verdict),
+   `domain/loop.py` (the run-loop state machine itself).
+
+3. **Is it orchestration — call a port, feed the result to a domain
+   function, call another port?**
+   → `application/`, as a use case in `application/usecases/` or inside
+   `application/runner.py`.
+
+4. **Is it argument parsing or terminal output formatting for a human?**
+   → `cli/`.
+
+**When in doubt, push logic inward.** A `cli/` command containing an
+`if/elif` deciding what a rate-limit response *means* is a bug: that
+decision belongs in `domain/classify.py`, testable with zero CLI process
+spun up.
+
+## The enforced import rules
+
+From `pyproject.toml`:
+
+```toml
+[[tool.importlinter.contracts]]
+name = "Onion layering"
+type = "layers"
+layers = ["claudeloop.cli", "claudeloop.bootstrap", "claudeloop.application", "claudeloop.domain"]
+
+[[tool.importlinter.contracts]]
+name = "Infrastructure only reachable from bootstrap"
+type = "forbidden"
+source_modules = ["claudeloop.domain", "claudeloop.application"]
+forbidden_modules = ["claudeloop.infrastructure"]
+```
+
+Concretely:
+
+- `domain/*.py` may `import` from stdlib and other `domain/*` modules ONLY.
+  No `typing.Protocol`-based ports either — those live one layer out.
+- `application/*.py` may import `domain` and stdlib. Ports are
+  `typing.Protocol`, never an ABC a concrete adapter must inherit from —
+  this is what keeps `application/` from ever needing to import
+  `infrastructure/` just to name a type.
+- `infrastructure/*.py` may import `domain`, `application`, and any
+  third-party package. This is the ONLY place `anthropic` or
+  `claude_agent_sdk` appears in an `import` statement anywhere in
+  `src/claudeloop/`.
+- `cli/*.py` calls into `application/` use cases obtained from
+  `bootstrap.build_runner(...)` (or equivalent) — never constructs an
+  `infrastructure/` adapter directly.
+- `bootstrap.py` is the single seam permitted to import from every layer —
+  it's where a concrete adapter (e.g.
+  `infrastructure.agent.gateway.ClaudeAgentGateway`) gets wired into the
+  `Protocol` port `application/ports.py` declares (e.g. `AgentGateway`).
+
+## Verifying your change respects the contract
+
+```bash
+lint-imports
+```
+
+Run this before committing any new module. It's also a `pre-commit` hook and
+runs in CI (`ci.yml`). A violation names the exact contract broken —
+"Onion layering" or "Infrastructure only reachable from bootstrap" — and the
+offending import chain.
+
+## Full reference
+
+See `docs/architecture/overview.md` for the complete layer table and
+`docs/architecture/decisions/0001-onion-architecture-with-import-linter.md`
+for why this was chosen over convention-only layering. See
+`docs/architecture/ports-and-adapters.md` for the planned port list
+(M2+) and why ports are `Protocol` rather than ABC.

claudeloop-0.2.0/.claude/skills/claudeloop-docs/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: claudeloop-docs
+description: Explains where different kinds of content belong in this repo (CLAUDE.md vs .claude/skills/ vs docs/), how to build and strict-check the MkDocs Material site, and the writing conventions used throughout (Roadmap admonitions, relative links, ADR format). Use this whenever writing or editing any file under docs/, whenever deciding whether new content belongs in CLAUDE.md, a skill, or docs/, whenever the user asks about documentation structure, or before adding a page to mkdocs.yml's nav. Make sure to consult this before adding procedural, multi-step content to CLAUDE.md directly — CLAUDE.md is deliberately kept short and holds only facts; procedures belong in a skill instead, and getting this wrong bloats the context every single session pays for.
+allowed-tools: Read Grep Glob Bash(mkdocs *)
+---
+
+# claudeloop documentation
+
+## Where content belongs — the decision table
+
+| Content | Goes in |
+|---|---|
+| An always-true fact, cheap to state, every session needs | `CLAUDE.md` — kept deliberately SHORT, a router not a manual |
+| A procedure for working on a specific part of this codebase | `.claude/skills/<name>/SKILL.md` |
+| User-facing "how do I..." | `docs/getting-started/` or `docs/guides/` |
+| System design — what exists, how pieces fit | `docs/architecture/` |
+| The reasoning behind ONE specific hard decision | `docs/architecture/decisions/` — an ADR |
+| Generated API docs | `docs/reference/api.md` via `mkdocstrings` — never hand-write signatures that already exist as docstrings |
+| Contributor process | `docs/contributing/` |
+| Historical plans, preserved verbatim once superseded | `docs/plans/` |
+
+**The CLAUDE.md/skill dividing line, precisely: CLAUDE.md holds facts,
+skills hold procedures.** If you're about to add a multi-step "when doing
+X, do Y then Z" instruction to `CLAUDE.md`, it belongs in a skill instead —
+skills load into context only when relevant, so long procedural content
+there is free until needed, while everything in `CLAUDE.md` costs context
+on every single session regardless of relevance.
+
+## Building and checking the site
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve      # local preview at http://127.0.0.1:8000, live-reloads
+mkdocs build --strict   # what CI runs — fails on ANY warning, most commonly a broken link
+```
+
+Run `mkdocs build --strict` before opening a PR that touches `docs/` — it's
+exactly what `docs.yml` runs in CI.
+
+## Writing conventions
+
+- **Plain markdown only** — the extensions enabled in `mkdocs.yml`
+  (admonitions, code fences, tables) and nothing docs-only-syntax beyond
+  that, because every page must read correctly as plain text on GitHub
+  (`CLAUDE.md` and the skills link straight to file paths, not built-site
+  URLs).
+- **Relative links, not absolute site URLs** — so links work both on GitHub
+  and in the built MkDocs site.
+- **Explain "why," not just "what."** A page restating a function signature
+  the code already shows isn't earning its place — put reasoning a stranger
+  can't get from the code alone into the page. This is exactly the ADRs'
+  purpose.
+- **Mark roadmap content with `!!! note "Roadmap"`** at the top of any page
+  describing a not-yet-built milestone, so a reader never mistakes a design
+  intention for current behavior. `grep -rl '!!! note "Roadmap"' docs/`
+  finds every page that needs revisiting as a milestone lands.
+- **New page → add it to `mkdocs.yml`'s `nav:`** or `mkdocs build --strict`
+  will not error (an orphaned page is not itself a strict-mode failure) but
+  the page becomes unreachable from the site nav — always add it.
+
+## ADR format
+
+Follow the existing files in `docs/architecture/decisions/` exactly:
+`NNNN-kebab-case-title.md`, sections `## Status` / `## Context` / `##
+Decision` / `## Consequences`, four-digit zero-padded sequential numbering.
+Add a new ADR when a PR makes a hard, non-obvious design call worth
+preserving the reasoning for — not for routine changes.
+
+## Full reference
+
+`docs/contributing/documentation.md`.

claudeloop-0.2.0/.claude/skills/claudeloop-domain-model/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: claudeloop-domain-model
+description: Explains every value object and ADT in src/claudeloop/domain/ — CapacityState (Available/WindowExhausted/CreditsExhausted/AuthenticationFailed), TurnSignals classification, CompletionVerdict (Done/Continue/Blocked), the wait-probe policy in waiting.py, Budget/BudgetLedger, and the run-loop state machine in loop.py. Use this whenever reading, modifying, or extending anything in src/claudeloop/domain/ or tests/domain/, whenever the user asks about rate-limit classification, credits vs. rate limits, capacity states, completion detection, the waiting/backoff policy, or the run-loop state machine, and whenever adding a new domain type or branch. Make sure to consult this before touching domain/classify.py, domain/waiting.py, domain/completion.py, or domain/loop.py — the ordering of branches in each is deliberate and tested, and an out-of-order edit silently reintroduces bugs this project was specifically built to fix.
+allowed-tools: Read Grep Glob
+---
+
+# claudeloop domain model
+
+Everything in `src/claudeloop/domain/` is a frozen dataclass or a closed
+union of them, has zero third-party imports, and requires 100% test
+coverage. This skill is the map; for full prose explanation with rationale
+see `docs/architecture/domain-model.md`.
+
+## `capacity.py` — CapacityState
+
+```python
+CapacityState = Available | WindowExhausted | CreditsExhausted | AuthenticationFailed
+```
+
+**The single most important fact in this codebase**: `CreditsExhausted` has
+**no `resets_at` field at all** — not `None`, the type literally doesn't
+carry one — because waiting for a clock can never fix an empty credits
+balance. `WindowExhausted` carries `resets_at: datetime | None`.
+`is_waitable(state)` is `False` only for `AuthenticationFailed`.
+
+**Never conflate these two states** and never add a `resets_at` field to
+`CreditsExhausted` "for consistency" — that would silently reintroduce the
+exact bug (`claudeloop` replacing sleeping-an-hour-forever with something
+smarter) this project exists to fix.
+
+## `classify.py` — TurnSignals → CapacityState
+
+`classify(signals: TurnSignals) -> CapacityState`. Reads **three
+independent SDK signals** (a `RateLimitEvent`, `ResultMessage
+.api_error_status`, `AssistantMessage.error`) — never trust
+`RateLimitEvent` alone; it's reportedly dropped on some adapter paths.
+
+**Ordering is load-bearing, in this exact sequence:**
+
+1. `assistant_error == "authentication_failed"` → `AuthenticationFailed`, checked FIRST, outranks everything.
+2. `rate_limit_status == "allowed_warning"` → `Available` (NOT a rejection — this is the exact false positive that caused multi-day cooldowns in the legacy script).
+3. A rejection signal present → split further: credit signals (`error_code == "credits_required"`, `disabled_reason == "out_of_credits"`, a set `overage_disabled_reason`) win over a stray `resets_at` — check credits BEFORE falling through to `WindowExhausted`.
+4. Anything else rejected → `WindowExhausted`, falling back to `rate_limit_type="unknown", resets_at=None` if thin.
+
+If you're editing `classify.py`, preserve this order and re-run
+`tests/domain/test_classify.py` — every branch above has a dedicated test
+asserting it, including the adversarial case where a `resets_at` is present
+alongside a credits signal (credits must still win).
+
+## `completion.py` — CompletionVerdict
+
+```python
+CompletionVerdict = Done | Continue | Blocked
+```
+
+Primary signal: `StructuredVerdict` from `ClaudeAgentOptions.output_format`
+(`{complete, remaining_work, blocked_on, summary}`). `blocked_on` outranks
+`complete` — never let a turn claim both. Fallback (only when `structured is
+None`): substring-match `CLAUDELOOP_TASK_FULLY_COMPLETE` (or the configured
+marker) in raw output text — this is a fallback, not the primary path, and
+must stay that way; the substring approach has two documented failure modes
+(collision with user prompt text, truncation inside a limit message).
+
+## `waiting.py` — WaitPolicyConfig & next_probe_instant()
+
+`next_probe_instant(state, *, now, started_waiting_at, probe_count, config)
+-> datetime`. **Never returns a duration to sleep — always the next instant
+to probe.** Behavior differs by `CapacityState` type:
+
+- `CreditsExhausted` — exponential backoff, `credits_probe_interval`
+  (default 120s) to `credits_probe_ceiling` (default 600s). **Compute the
+  backoff in float seconds and clamp to the ceiling BEFORE constructing a
+  `timedelta`** — `interval * factor**probe_count` unclamped overflows
+  `timedelta`'s magnitude limit at realistic probe counts. A Hypothesis
+  property test caught this during development; don't reintroduce it.
+- `WindowExhausted(resets_at=X)` — `min(X + reset_grace, now +
+  window_probe_interval)`. Never trust a far-future `resets_at` alone; the
+  interval bound is what catches an early overage lift or credit top-up.
+- `WindowExhausted(resets_at=None)` — falls back to `window_probe_interval`.
+
+`config.max_wait`, when set, clamps every candidate to
+`started_waiting_at + max_wait`; `wait_exceeded()` is the paired "give up"
+check.
+
+**Any new numeric field on `WaitPolicyConfig` needs a `__post_init__`
+validation AND a Hypothesis property test** covering its invariant across
+the full input space — not just hand-picked examples. See
+`tests/domain/test_waiting.py` for the existing property tests as a
+template.
+
+## `budget.py` — Budget, BudgetLedger
+
+Immutable. `spend_turn()` / `spend_attempt()` return a **new** ledger, never
+mutate. `any_exhausted` ORs `turns_exhausted | dollars_exhausted |
+attempts_exhausted`. An unset cap (`None`) is never exhausted.
+
+## `loop.py` — the run-loop state machine
+
+`Phase = PREFLIGHT | RUNNING | WAITING | PROBING | COMPLETE | FAILED`.
+Three pure decision functions:
+
+- `decide_preflight(state, capacity, *, now)` — before spending the first
+  real turn.
+- `decide_after_turn(state, *, capacity, verdict, now)` — **the single most
+  important invariant in the whole codebase**: capacity is checked BEFORE
+  verdict, always. A `Done` verdict on a turn that also hit a rejection is
+  discarded — see `test_after_turn_limit_outranks_completion_claim`. Never
+  reorder this check.
+- `decide_after_probe(state, capacity, *, now, config)` — after a throwaway
+  probe while waiting.
+
+`Decision = SendTurn | RunProbe | ScheduleProbe | Finish` — a closed union
+the `application/runner.py` executor pattern-matches
+exhaustively, never partially.
+
+## `plan.py` / `session.py`
+
+`WorkPlan.parse(markdown)` extracts checkbox items (`- [ ]` / `- [x]`, both
+bullet styles, either case). `with_items_marked_done(frozenset)` reconciles
+a turn's `remaining_work` back against the plan. `SessionSelector =
+PlanFileSelector | ExplicitSessionSelector | MostRecentSessionSelector` —
+the legacy script's three input modes as a closed union instead of
+if/elif on optional fields.
+
+## Full reference
+
+`docs/architecture/domain-model.md` (complete prose walkthrough),
+`docs/architecture/run-loop-state-machine.md` (the state machine in detail,
+including the credit-top-up worked example),
+`docs/architecture/decisions/0003-*.md` through `0004-*.md` (why
+`CreditsExhausted` is distinct, why probing beats sleeping).

claudeloop-0.2.0/.claude/skills/claudeloop-quality-gates/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: claudeloop-quality-gates
+description: Covers how to run and FIX every quality gate in this repo — ruff (lint + format), mypy --strict, pytest with per-layer coverage, import-linter (lint-imports), bandit, and pip-audit. Use this whenever a quality gate fails locally or in CI, whenever the user asks how to lint, format, type-check, or run security scans on this codebase, or before opening a PR to run the full gate set proactively. Make sure to consult this whenever a ruff, mypy, lint-imports, or bandit error appears in tool output — it gives the exact fix command for each gate rather than requiring you to guess at generic remediation.
+allowed-tools: Bash(ruff *) Bash(mypy *) Bash(pytest *) Bash(lint-imports) Bash(bandit *) Bash(pip-audit *) Bash(pre-commit *) Read
+---
+
+# claudeloop quality gates — run and fix
+
+## The full set, in the order CI runs them
+
+```bash
+ruff check src tests
+ruff format --check src tests
+mypy src/claudeloop
+pytest
+lint-imports
+bandit -q -r src/claudeloop
+pip-audit
+```
+
+Or the pre-commit-wired subset against your working tree:
+
+```bash
+pre-commit run --all-files
+```
+
+## Fixing each gate
+
+| Gate | Symptom | Fix |
+|---|---|---|
+| `ruff check` | Lint error | `ruff check --fix src tests` for auto-fixable rules; hand-edit the rest. Rule set: `E, F, I, UP, B, SIM, C4` (see `[tool.ruff.lint]` in `pyproject.toml`). |
+| `ruff format --check` | Formatting diff | `ruff format src tests` |
+| `mypy` | Type error | Add/correct annotations. `strict = true` repo-wide — no bare `Any` without a documented reason. `domain/` and `application/` in particular must type-check cleanly with zero suppressions. |
+| `pytest` | Test failure or coverage below the per-layer floor | See the `claudeloop-testing` skill — check whether a branch is genuinely untested (add a test) vs. genuinely unreachable (a justified `# pragma: no cover`) |
+| `lint-imports` | Onion-layering violation | See the `claudeloop-architecture` skill — the fix is almost always moving the offending code to the correct layer, not suppressing the contract |
+| `bandit` | Flagged security pattern | Either fix the underlying issue, or — for a genuine false positive like an exhaustiveness `assert` on a closed union — add `# nosec B1xx` with an inline comment stating *why* it's safe. Two real examples exist in `src/claudeloop/domain/loop.py`; match that level of justification, don't just silence the warning. |
+| `pip-audit` | Known CVE in a dependency | Bump the dependency. If no fix is available yet, this needs to be surfaced explicitly (in the PR description or an issue), not silently ignored — this project handles API credentials and bypasses permission prompts by design, so dependency CVEs are higher-stakes than usual. See `SECURITY.md`. |
+
+## Bandit `# nosec` — the bar for using it
+
+Only for a verified false positive, never to silence a real finding faster.
+The comment must explain the specific reason the pattern is safe *here*,
+matching this repo's existing style:
+
+```python
+# Precondition, not a security gate: CompletionVerdict is the closed union
+# {Done, Blocked, Continue} and both other members are handled above, so this
+# is exhaustive by construction — asserted here to fail loudly if a future
+# variant is added to the union without a matching branch here.
+assert isinstance(verdict, Continue)  # nosec B101
+```
+
+## Before opening a PR
+
+Run the full gate set (not just the pre-commit subset — `pytest` with
+coverage and `pip-audit` aren't pre-commit hooks) once locally. A PR that
+fails CI on a gate that would have caught locally wastes a review round.
+
+## Full reference
+
+`docs/contributing/development.md#running-the-quality-gates-locally`,
+`CONTRIBUTING.md#quality-gates`.

claudeloop-0.2.0/.claude/skills/claudeloop-releasing/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: claudeloop-releasing
+description: Explains the gitflow branch model (feature/* -> develop -> main), Conventional Commits requirements and types, how release-please automates version bumps and changelog generation from commit history, and how PyPI Trusted Publishing (OIDC) works via publish-to-pypi.yml. Use this whenever creating a branch, writing a commit message, opening a PR, asking about versioning, releases, or publishing to PyPI, or when a commit-msg hook rejects a commit. Make sure to consult this before writing any commit message in this repo — the commit-msg git hook enforces Conventional Commits and will reject anything that doesn't match, and getting the branch target or merge strategy wrong breaks the automated release pipeline downstream.
+allowed-tools: Bash(git *) Read
+---
+
+# claudeloop releasing — gitflow + Conventional Commits + Trusted Publishing
+
+## Branch model
+
+```
+main         ← always releasable; release-please opens release PRs here
+  ▲ merge commit (preserves individual conventional commits for release-please)
+develop      ← integration branch; feature branches target this
+  ▲ squash-merge (one conventional-commit-titled squash per feature)
+feature/*    ← your work — branch from develop, never from main
+```
+
+**Never branch from `main` directly, never target `main` with a feature
+PR.** Feature work is `git checkout -b feature/<short-description> develop`,
+PR into `develop`. `develop` → `main` happens as a merge commit (not
+squashed) specifically so release-please can parse the individual commits
+when it moves `main`.
+
+## Conventional Commits — required, enforced by a git hook
+
+Every commit message: `<type>[optional scope]: <description>`. The
+`commit-msg` hook (installed by `pre-commit install`) rejects anything else
+in `--strict` mode. Types and what each triggers on release:
+
+| Type | Use for | Bump |
+|---|---|---|
+| `feat` | new feature | minor |
+| `fix` | bug fix | patch |
+| `feat!` / `fix!` / `BREAKING CHANGE:` footer | breaking change | major |
+| `docs` `style` `refactor` `test` `build` `ci` `chore` | no functional/patch/minor change | none |
+| `perf` | performance improvement | patch |
+| `revert` | reverts a prior commit | depends |
+
+```
+feat(domain): add CreditsExhausted as a distinct capacity state
+fix(waiting): clamp exponential backoff before constructing timedelta
+```
+
+Scope in parentheses is optional but strongly preferred — it makes the
+generated changelog dramatically more scannable. If a commit is rejected:
+your editor still has what you typed; fix the first line and commit again.
+
+## release-please — fully automated, one human gate
+
+release-please watches `main` and maintains a single standing
+`chore(release): x.y.z` PR, its body the generated changelog for everything
+merged since the last release, its diff bumping `pyproject.toml`'s
+`[project].version` and updating `CHANGELOG.md`. **Merging that PR is the
+release** — that merge is the human review gate; nothing else about
+versioning needs to happen by hand. Never hand-edit `CHANGELOG.md` above
+the `<!-- release-please starts and maintains ... -->` marker — it will be
+overwritten on the next run.
+
+## Publishing — PyPI Trusted Publishing (OIDC), no stored token
+
+On the release-please PR's merge, a GitHub Release is created, which
+triggers `publish-to-pypi.yml` (`on: release: published`). Two jobs: a
+`build` job with no `id-token` permission (builds the sdist/wheel, runs
+`twine check --strict`), then a `publish` job scoped to the GitHub
+environment `pypi` (requires manual approval — a second human gate) with
+`permissions: id-token: write` and nothing else, publishing via
+`pypa/gh-action-pypi-publish`. There is no PyPI API token anywhere in this
+repository's secrets — do not add one; it would disable the OIDC flow for
+no benefit.
+
+**The workflow filename `publish-to-pypi.yml` is load-bearing** — PyPI's
+pending-publisher configuration matches on it exactly. Do not rename that
+file without also updating the PyPI project's Trusted Publisher
+configuration to match.
+
+## Full reference
+
+`docs/contributing/release-process.md` (the complete manual setup steps and
+verification checklist), `docs/contributing/development.md#the-branch-model-gitflow`,
+`CONTRIBUTING.md`.