codexloop 0.3.0__tar.gz → 0.3.1__tar.gz

codexloop-0.3.1/.agent/rules/codexloop-architecture.md

@@ -0,0 +1,29 @@
+# codexloop-architecture (Antigravity mirror of `.claude/skills/codexloop-architecture/SKILL.md`)
+
+
+# codexloop architecture
+
+Dependencies point inward. `import-linter` enforces this in CI.
+
+```
+src/codexloop/
+├── 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 openai.
+├── cli/              # Typer. 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, or an SDK? → `infrastructure/`, behind a
+   `Protocol` in `application/interfaces/`. Never `import openai`
+   elsewhere.
+2. Pure decision, zero I/O? → `domain/`. Examples: `classify.py`,
+   `waiting.py`, `completion.py`, `capacity.py`.
+3. Orchestration (port → domain → port)? → `application/`.
+4. Argument parsing / terminal formatting? → `cli/`.
+
+When in doubt, push logic inward. `lint-imports` names the broken contract.
+
+See ADR 0001.

codexloop-0.3.1/.agent/rules/codexloop-completion.md

@@ -0,0 +1,42 @@
+# codexloop-completion (Antigravity mirror of `.claude/skills/codexloop-completion/SKILL.md`)
+
+
+# codexloop completion detection
+
+`CompletionEvaluator` in `domain/completion.py` maps `TurnSignals` +
+`CapacityState` into a `CompletionVerdict`.
+
+## CompletionVerdict variants
+
+```python
+Done  # task fully complete
+Continue  # remaining: list[str]
+Blocked  # reason: str — human intervention needed
+```
+
+## Three-layer evaluation
+
+**Capacity rejection always outranks a completion claim.** If the turn is
+not `Available`, return `Continue` regardless of structured output or
+markers.
+
+For an `Available` turn, the layers are:
+
+1. **Structured output** (`StructuredOutput` tool call result):
+   - `blocked_on` set → `Blocked(reason=blocked_on)`.
+   - `complete: true` and `remaining_work: []` → `Done`.
+   - `complete: true` but `remaining_work` not empty → `Continue`.
+   - `complete: false` → `Continue(remaining=remaining_work)`.
+
+2. **Marker on own line**: if `CODEXLOOP_TASK_FULLY_COMPLETE` appears on
+   its own line in the final message → `Done`.
+
+3. **Fallback**: `Continue(remaining=[])`.
+
+The marker check uses `_marker_on_own_line(message, done_marker)`: the
+string must be the only non-whitespace on the line. Partial matches or
+inline occurrences do not count.
+
+**Never treat a non-`Available` turn as `Done`.** Rate-limit windows and
+transient errors are waitable; completion is deferred until capacity
+returns.

codexloop-0.3.1/.agent/rules/codexloop-docs.md

@@ -0,0 +1,50 @@
+# codexloop-docs (Antigravity mirror of `.claude/skills/codexloop-docs/SKILL.md`)
+
+
+# codexloop docs
+
+User-facing documentation lives in `docs/` and is built with
+mkdocs-material.
+
+## Structure
+
+```
+docs/
+├── index.md                      # landing page
+├── getting-started.md
+├── guides/                       # how-to guides
+│   └── rest-api-surface.md
+├── architecture/
+│   ├── index.md
+│   └── adr/                      # Architecture Decision Records
+│       ├── index.md
+│       ├── 0001-onion-import-linter.md
+│       └── 0002-subprocess-codex-exec.md
+├── contributing.md
+└── publishing.md
+```
+
+## Commands
+
+```bash
+mkdocs serve          # live preview at http://127.0.0.1:8000
+mkdocs build --strict # fail on warnings
+```
+
+`--strict` runs in CI via `.github/workflows/docs.yml`.
+
+## ADRs
+
+Architecture Decision Records follow the Nygard format. Each ADR gets a
+number (0001, 0002, ...) and a kebab-case title. Add new ADRs to
+`docs/architecture/adr/index.md`.
+
+## Excluded paths
+
+`mkdocs.yml` excludes `plans/**` and `superpowers/**` from the built
+site. These are workspace-specific and not user-facing.
+
+## Before pushing doc changes
+
+Run `mkdocs build --strict` to catch broken links, missing pages, and
+markdown errors.

codexloop-0.3.1/.agent/rules/codexloop-quota-and-capacity.md

@@ -0,0 +1,44 @@
+# codexloop-quota-and-capacity (Antigravity mirror of `.claude/skills/codexloop-quota-and-capacity/SKILL.md`)
+
+
+# codexloop quota and capacity
+
+`QuotaExhausted` is a billing wall with no `resets_at` — it is **never
+waitable** and always needs a human to top up. Rate-limit windows *are*
+waitable.
+
+## CapacityState variants
+
+```python
+Available  # green light
+ThrottleExhausted  # retry_after: timedelta | None
+WindowExhausted  # resets_at: datetime | None, window: str
+QuotaExhausted  # reason: str — TERMINAL, never waitable
+AuthFailed  # reason: str — TERMINAL
+TransientBackendError  # retry_after: timedelta | None
+```
+
+`is_waitable(state)` returns `False` only for `QuotaExhausted` and
+`AuthFailed`.
+
+## Body-first classification
+
+`classify(signals)` in `domain/classify.py` maps `TurnSignals` to a
+`CapacityState` using this ladder:
+
+1. **Body wins.** `error.code` / `error.type` outrank HTTP status.
+2. Auth: `error.code` / `error.type` in `ErrorClass.AUTH`, or status 401
+   → `AuthFailed`.
+3. Quota: `error.code` / `error.type` in `ErrorClass.QUOTA` →
+   `QuotaExhausted` (terminal).
+4. Window: `ErrorClass.WINDOW` → `WindowExhausted` with `resets_at` from
+   plan windows.
+5. Throttle: `ErrorClass.THROTTLE` → `ThrottleExhausted` with
+   `retry_after`.
+6. Transient: `ErrorClass.TRANSIENT` or status 5xx →
+   `TransientBackendError`.
+7. Status 429 with no body marker → `WindowExhausted(resets_at=None)`.
+8. Fallback: `Available`.
+
+High `used_percent` never outranks a billing marker. Completion claims
+never outrank capacity rejection.

codexloop-0.3.1/.agent/rules/codexloop-releasing.md

@@ -0,0 +1,51 @@
+# codexloop-releasing (Antigravity mirror of `.claude/skills/codexloop-releasing/SKILL.md`)
+
+
+# codexloop releasing
+
+## Gitflow
+
+```
+develop (default branch) → main (releases)
+```
+
+1. Feature PRs squash into `develop`.
+2. `develop` merge-commits into `main` when ready to release.
+3. release-please opens a PR on `main` when it detects conventional
+   commits since the last tag.
+4. Merging the release PR publishes to PyPI.
+
+## Workflows
+
+- **`ci.yml`**: runs on every push. Tests, linting, type checks, per-layer
+  coverage, import-linter, bandit, pip-audit.
+- **`publish-testpypi.yml`**: publishes to TestPyPI on every `develop`
+  push. **Known gap: no test gate.** This workflow builds and publishes
+  without running tests first. It trusts that CI passed.
+- **`release-please.yml`**: opens a release PR on `main` when conventional
+  commits land. Merging that PR publishes to PyPI (via GitHub Actions +
+  PyPI trusted publishing).
+
+## release-please
+
+Configured in `release-please-config.json`:
+
+```json
+{
+  "packages": {
+    ".": {
+      "release-type": "python",
+      "package-name": "codexloop",
+      "changelog-path": "CHANGELOG.md"
+    }
+  }
+}
+```
+
+It maintains `CHANGELOG.md` automatically from conventional commits.
+
+## Before merging develop → main
+
+1. All CI gates green on `develop`.
+2. TestPyPI publish succeeded (workflow run shows no errors).
+3. CHANGELOG.md reflects all user-facing changes since last release.

codexloop-0.3.1/.agent/rules/codexloop-rest-surface.md

@@ -0,0 +1,40 @@
+# codexloop-rest-surface (Antigravity mirror of `.claude/skills/codexloop-rest-surface/SKILL.md`)
+
+
+# codexloop REST surface
+
+`codexloop api` generates a 1:1 CLI mirror of the OpenAI Python SDK's REST
+methods. The tree is code-generated from the SDK itself, not maintained by
+hand.
+
+## api_baseline.json drift gate
+
+`api_baseline.json` freezes the **OpenAI SDK's** method count and list,
+not codexloop's. It is a snapshot of what the SDK exposes, not what
+codexloop adds.
+
+A test fails when:
+
+- The SDK adds or removes methods (changes `method_count`).
+- Methods appear or disappear from the `methods` list.
+- `local_helpers` (like `chat.completions.stream`) change.
+
+This gate prevents SDK upgrades from silently altering the API surface
+without review.
+
+## Refreshing the baseline
+
+After an intentional SDK upgrade, refresh the baseline:
+
+```bash
+codexloop api --help  # generates the tree
+# The test writes the new baseline to api_baseline.json
+pytest tests/cli/test_api.py --update-baseline
+```
+
+Commit the updated `api_baseline.json` in the same PR as
+`pyproject.toml` changes.
+
+**Never refresh the baseline for unrelated PRs.** A drift failure
+during SDK upgrade is expected and intentional — it forces you to
+inspect what changed.

codexloop-0.3.0/.cursor/rules/codexloop-run.mdc → codexloop-0.3.1/.agent/rules/codexloop-run.md

@@ -1,8 +1,5 @@
----
-description: Run and debug codexloop autonomous sessions.
-globs:
-alwaysApply: false
----
+# codexloop-run (Antigravity mirror of `.claude/skills/codexloop-run/SKILL.md`)
+
 
 # codexloop-run
 

codexloop-0.3.1/.agent/rules/codexloop-testing.md

@@ -0,0 +1,34 @@
+# codexloop-testing (Antigravity mirror of `.claude/skills/codexloop-testing/SKILL.md`)
+
+
+# codexloop testing
+
+```
+tests/domain/            # pure unit + Hypothesis
+tests/application/       # fakes for every port (application/interfaces/)
+tests/infrastructure/    # adapters
+tests/shim/              # fake_codex.py + fake_appserver.py — executable fakes
+tests/live/              # marker: live — real OpenAI account, opt-in
+```
+
+```bash
+pytest                 # skips live (default -m "not live and not system")
+pytest -m system       # real FS/git + scripted agent
+pytest -m live         # needs OPENAI_API_KEY
+```
+
+- **Fakes over mocks.** Implement the `Protocol`; `mypy --strict` checks it.
+- **Executable shims.** `fake_codex.py` and `fake_appserver.py` in
+  `tests/shim/` are genuine executables driven by env vars — the only such
+  fakes in the fleet. They let you script exact output sequences without
+  touching the OpenAI SDK.
+- **No `time.sleep` in tests.** `FakeClock` / `FakeSleeper`.
+- Hypothesis for numeric / time-based invariants.
+- `# pragma: no cover` needs a reason.
+- **100% branch coverage per layer**, enforced by gate:
+  ```bash
+  pytest -q --cov=codexloop.domain --cov-fail-under=100
+  pytest -q --cov=codexloop.application --cov-fail-under=100
+  pytest -q --cov=codexloop.infrastructure --cov-fail-under=100
+  pytest -q --cov=codexloop.cli --cov-fail-under=100
+  ```

codexloop-0.3.1/.agents/skills/codexloop-architecture/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: codexloop-architecture
+description: Onion layers for codexloop (domain, application, infrastructure, cli), import-linter, and where new code belongs. Use before adding a module under src/codexloop/.
+allowed-tools: Read Grep Glob Bash(lint-imports)
+---
+
+# codexloop architecture
+
+Dependencies point inward. `import-linter` enforces this in CI.
+
+```
+src/codexloop/
+├── 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 openai.
+├── cli/              # Typer. 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, or an SDK? → `infrastructure/`, behind a
+   `Protocol` in `application/interfaces/`. Never `import openai`
+   elsewhere.
+2. Pure decision, zero I/O? → `domain/`. Examples: `classify.py`,
+   `waiting.py`, `completion.py`, `capacity.py`.
+3. Orchestration (port → domain → port)? → `application/`.
+4. Argument parsing / terminal formatting? → `cli/`.
+
+When in doubt, push logic inward. `lint-imports` names the broken contract.
+
+See ADR 0001.

codexloop-0.3.1/.agents/skills/codexloop-completion/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: codexloop-completion
+description: Three-layer completion evaluation (structured output → marker → continue), capacity rejection outranks completion claim. Use when working with completion.py.
+allowed-tools: Read Grep
+---
+
+# codexloop completion detection
+
+`CompletionEvaluator` in `domain/completion.py` maps `TurnSignals` +
+`CapacityState` into a `CompletionVerdict`.
+
+## CompletionVerdict variants
+
+```python
+Done  # task fully complete
+Continue  # remaining: list[str]
+Blocked  # reason: str — human intervention needed
+```
+
+## Three-layer evaluation
+
+**Capacity rejection always outranks a completion claim.** If the turn is
+not `Available`, return `Continue` regardless of structured output or
+markers.
+
+For an `Available` turn, the layers are:
+
+1. **Structured output** (`StructuredOutput` tool call result):
+   - `blocked_on` set → `Blocked(reason=blocked_on)`.
+   - `complete: true` and `remaining_work: []` → `Done`.
+   - `complete: true` but `remaining_work` not empty → `Continue`.
+   - `complete: false` → `Continue(remaining=remaining_work)`.
+
+2. **Marker on own line**: if `CODEXLOOP_TASK_FULLY_COMPLETE` appears on
+   its own line in the final message → `Done`.
+
+3. **Fallback**: `Continue(remaining=[])`.
+
+The marker check uses `_marker_on_own_line(message, done_marker)`: the
+string must be the only non-whitespace on the line. Partial matches or
+inline occurrences do not count.
+
+**Never treat a non-`Available` turn as `Done`.** Rate-limit windows and
+transient errors are waitable; completion is deferred until capacity
+returns.

codexloop-0.3.1/.agents/skills/codexloop-docs/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: codexloop-docs
+description: mkdocs-material, ADR structure, and doc build/serve commands. Use when adding documentation.
+allowed-tools: Read Bash(mkdocs *)
+---
+
+# codexloop docs
+
+User-facing documentation lives in `docs/` and is built with
+mkdocs-material.
+
+## Structure
+
+```
+docs/
+├── index.md                      # landing page
+├── getting-started.md
+├── guides/                       # how-to guides
+│   └── rest-api-surface.md
+├── architecture/
+│   ├── index.md
+│   └── adr/                      # Architecture Decision Records
+│       ├── index.md
+│       ├── 0001-onion-import-linter.md
+│       └── 0002-subprocess-codex-exec.md
+├── contributing.md
+└── publishing.md
+```
+
+## Commands
+
+```bash
+mkdocs serve          # live preview at http://127.0.0.1:8000
+mkdocs build --strict # fail on warnings
+```
+
+`--strict` runs in CI via `.github/workflows/docs.yml`.
+
+## ADRs
+
+Architecture Decision Records follow the Nygard format. Each ADR gets a
+number (0001, 0002, ...) and a kebab-case title. Add new ADRs to
+`docs/architecture/adr/index.md`.
+
+## Excluded paths
+
+`mkdocs.yml` excludes `plans/**` and `superpowers/**` from the built
+site. These are workspace-specific and not user-facing.
+
+## Before pushing doc changes
+
+Run `mkdocs build --strict` to catch broken links, missing pages, and
+markdown errors.

codexloop-0.3.1/.agents/skills/codexloop-quota-and-capacity/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: codexloop-quota-and-capacity
+description: QuotaExhausted has no reset field, body-first classification ladder, and waitability rules. Use when working with capacity.py or classify.py.
+allowed-tools: Read Grep
+---
+
+# codexloop quota and capacity
+
+`QuotaExhausted` is a billing wall with no `resets_at` — it is **never
+waitable** and always needs a human to top up. Rate-limit windows *are*
+waitable.
+
+## CapacityState variants
+
+```python
+Available  # green light
+ThrottleExhausted  # retry_after: timedelta | None
+WindowExhausted  # resets_at: datetime | None, window: str
+QuotaExhausted  # reason: str — TERMINAL, never waitable
+AuthFailed  # reason: str — TERMINAL
+TransientBackendError  # retry_after: timedelta | None
+```
+
+`is_waitable(state)` returns `False` only for `QuotaExhausted` and
+`AuthFailed`.
+
+## Body-first classification
+
+`classify(signals)` in `domain/classify.py` maps `TurnSignals` to a
+`CapacityState` using this ladder:
+
+1. **Body wins.** `error.code` / `error.type` outrank HTTP status.
+2. Auth: `error.code` / `error.type` in `ErrorClass.AUTH`, or status 401
+   → `AuthFailed`.
+3. Quota: `error.code` / `error.type` in `ErrorClass.QUOTA` →
+   `QuotaExhausted` (terminal).
+4. Window: `ErrorClass.WINDOW` → `WindowExhausted` with `resets_at` from
+   plan windows.
+5. Throttle: `ErrorClass.THROTTLE` → `ThrottleExhausted` with
+   `retry_after`.
+6. Transient: `ErrorClass.TRANSIENT` or status 5xx →
+   `TransientBackendError`.
+7. Status 429 with no body marker → `WindowExhausted(resets_at=None)`.
+8. Fallback: `Available`.
+
+High `used_percent` never outranks a billing marker. Completion claims
+never outrank capacity rejection.

codexloop-0.3.1/.agents/skills/codexloop-releasing/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: codexloop-releasing
+description: release-please, gitflow (develop → main), TestPyPI + PyPI publishing, and the known publish-testpypi gap. Use before cutting a release.
+allowed-tools: Read Bash(git *)
+---
+
+# codexloop releasing
+
+## Gitflow
+
+```
+develop (default branch) → main (releases)
+```
+
+1. Feature PRs squash into `develop`.
+2. `develop` merge-commits into `main` when ready to release.
+3. release-please opens a PR on `main` when it detects conventional
+   commits since the last tag.
+4. Merging the release PR publishes to PyPI.
+
+## Workflows
+
+- **`ci.yml`**: runs on every push. Tests, linting, type checks, per-layer
+  coverage, import-linter, bandit, pip-audit.
+- **`publish-testpypi.yml`**: publishes to TestPyPI on every `develop`
+  push. **Known gap: no test gate.** This workflow builds and publishes
+  without running tests first. It trusts that CI passed.
+- **`release-please.yml`**: opens a release PR on `main` when conventional
+  commits land. Merging that PR publishes to PyPI (via GitHub Actions +
+  PyPI trusted publishing).
+
+## release-please
+
+Configured in `release-please-config.json`:
+
+```json
+{
+  "packages": {
+    ".": {
+      "release-type": "python",
+      "package-name": "codexloop",
+      "changelog-path": "CHANGELOG.md"
+    }
+  }
+}
+```
+
+It maintains `CHANGELOG.md` automatically from conventional commits.
+
+## Before merging develop → main
+
+1. All CI gates green on `develop`.
+2. TestPyPI publish succeeded (workflow run shows no errors).
+3. CHANGELOG.md reflects all user-facing changes since last release.

codexloop-0.3.1/.agents/skills/codexloop-rest-surface/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: codexloop-rest-surface
+description: Generated `codexloop api` command tree, api_baseline.json drift gate, and how to refresh the baseline. Use when SDK upgrades change the surface.
+allowed-tools: Read Bash(codexloop api *)
+---
+
+# codexloop REST surface
+
+`codexloop api` generates a 1:1 CLI mirror of the OpenAI Python SDK's REST
+methods. The tree is code-generated from the SDK itself, not maintained by
+hand.
+
+## api_baseline.json drift gate
+
+`api_baseline.json` freezes the **OpenAI SDK's** method count and list,
+not codexloop's. It is a snapshot of what the SDK exposes, not what
+codexloop adds.
+
+A test fails when:
+
+- The SDK adds or removes methods (changes `method_count`).
+- Methods appear or disappear from the `methods` list.
+- `local_helpers` (like `chat.completions.stream`) change.
+
+This gate prevents SDK upgrades from silently altering the API surface
+without review.
+
+## Refreshing the baseline
+
+After an intentional SDK upgrade, refresh the baseline:
+
+```bash
+codexloop api --help  # generates the tree
+# The test writes the new baseline to api_baseline.json
+pytest tests/cli/test_api.py --update-baseline
+```
+
+Commit the updated `api_baseline.json` in the same PR as
+`pyproject.toml` changes.
+
+**Never refresh the baseline for unrelated PRs.** A drift failure
+during SDK upgrade is expected and intentional — it forces you to
+inspect what changed.

codexloop-0.3.1/.agents/skills/codexloop-testing/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: codexloop-testing
+description: Fakes over mocks, FakeClock/FakeSleeper, Hypothesis, pytest markers, per-layer 100% coverage. Consult before adding tests or mocks.
+allowed-tools: Read Grep Glob Bash(pytest *)
+---
+
+# codexloop testing
+
+```
+tests/domain/            # pure unit + Hypothesis
+tests/application/       # fakes for every port (application/interfaces/)
+tests/infrastructure/    # adapters
+tests/shim/              # fake_codex.py + fake_appserver.py — executable fakes
+tests/live/              # marker: live — real OpenAI account, opt-in
+```
+
+```bash
+pytest                 # skips live (default -m "not live and not system")
+pytest -m system       # real FS/git + scripted agent
+pytest -m live         # needs OPENAI_API_KEY
+```
+
+- **Fakes over mocks.** Implement the `Protocol`; `mypy --strict` checks it.
+- **Executable shims.** `fake_codex.py` and `fake_appserver.py` in
+  `tests/shim/` are genuine executables driven by env vars — the only such
+  fakes in the fleet. They let you script exact output sequences without
+  touching the OpenAI SDK.
+- **No `time.sleep` in tests.** `FakeClock` / `FakeSleeper`.
+- Hypothesis for numeric / time-based invariants.
+- `# pragma: no cover` needs a reason.
+- **100% branch coverage per layer**, enforced by gate:
+  ```bash
+  pytest -q --cov=codexloop.domain --cov-fail-under=100
+  pytest -q --cov=codexloop.application --cov-fail-under=100
+  pytest -q --cov=codexloop.infrastructure --cov-fail-under=100
+  pytest -q --cov=codexloop.cli --cov-fail-under=100
+  ```

codexloop-0.3.1/.claude/skills/codexloop-architecture/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: codexloop-architecture
+description: Onion layers for codexloop (domain, application, infrastructure, cli), import-linter, and where new code belongs. Use before adding a module under src/codexloop/.
+allowed-tools: Read Grep Glob Bash(lint-imports)
+---
+
+# codexloop architecture
+
+Dependencies point inward. `import-linter` enforces this in CI.
+
+```
+src/codexloop/
+├── 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 openai.
+├── cli/              # Typer. 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, or an SDK? → `infrastructure/`, behind a
+   `Protocol` in `application/interfaces/`. Never `import openai`
+   elsewhere.
+2. Pure decision, zero I/O? → `domain/`. Examples: `classify.py`,
+   `waiting.py`, `completion.py`, `capacity.py`.
+3. Orchestration (port → domain → port)? → `application/`.
+4. Argument parsing / terminal formatting? → `cli/`.
+
+When in doubt, push logic inward. `lint-imports` names the broken contract.
+
+See ADR 0001.