whiletrue 0.1.0__tar.gz

whiletrue-0.1.0/.editorconfig

@@ -0,0 +1,11 @@
+root = true
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4

whiletrue-0.1.0/.envrc

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+export DIRENV_WARN_TIMEOUT=20s
+
+eval "$(devenv direnvrc)"
+
+# The use_devenv function supports passing flags to the devenv command
+# For example: use devenv --impure --option services.postgres.enable:bool true
+use devenv

whiletrue-0.1.0/.github/ISSUE_TEMPLATE/task.md

@@ -0,0 +1,16 @@
+---
+name: Task
+about: A numbered item from docs/todo.md
+labels: task
+---
+
+**Todo item #:**
+
+**Milestone:** M0 / M1 / M2 / M3 / M4 / v0.1
+
+## Scope
+
+## Acceptance criteria
+
+- [ ] Tests
+- [ ] Docs

whiletrue-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## Summary
+
+Closes #
+
+## Checklist
+
+- [ ] Tests written first; `poe check` passes
+- [ ] User docs and `docs/architecture.md` updated (or N/A, with reason)
+- [ ] `docs/todo.md` item(s) ticked
+- [ ] Human has reviewed every line

whiletrue-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,13 @@
+name: CI
+on:
+  push: { branches: [main] }
+  pull_request:
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with: { enable-cache: true }
+      - run: uv sync --all-groups --locked
+      - run: uv run poe check

whiletrue-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release
+# Pushing a tag like v0.1.0 checks, builds and publishes to PyPI (trusted publishing: no token
+# is stored; configure the project on PyPI first), then creates the GitHub release.
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with: { enable-cache: true }
+      - run: uv sync --all-groups --locked
+      - run: uv run poe check
+      - name: The tag must match the package version
+        run: test "v$(uv run python -c 'import importlib.metadata as m; print(m.version("whiletrue"))')" = "${GITHUB_REF_NAME}"
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with: { name: dist, path: dist/ }
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - uses: pypa/gh-action-pypi-publish@release/v1
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - run: gh release create "$GITHUB_REF_NAME" dist/* --title "$GITHUB_REF_NAME" --notes-file CHANGELOG.md
+        env: { GH_TOKEN: "${{ github.token }}" }

whiletrue-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+.coverage
+coverage/
+.pytest_cache/
+.ruff_cache/
+.whiletrue/
+.env
+.env.*
+.DS_Store
+*.log
+
+# devenv / direnv
+.devenv*
+devenv.local.nix
+devenv.local.yaml
+.direnv/
+human-test/

whiletrue-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.0 (first release)
+
+whiletrue runs configurable pipelines of agentic and deterministic steps around coding agents.
+
+**Engine**
+- Typed modules with outcome ports (`ok`, `fail`, `needs_human`, `skip`, `rejected`), a plugin API (entry points), a static validator, and a SQLite-backed runtime with an append-only event log.
+- Control flow: `sequence`, `tap`, `loop`, `map` (optionally parallel), `parallel`, `switch`, `retry`, `try`; CEL expressions; composites with params and ports; recipes `ralph`, `review-pass`, `review-respond`, `issue-loop`.
+- Reproducibility: `whiletrue.lock`, run hashes, result cache, record and `replay`.
+- Parallel items with dependencies, `max_agents`, an item state machine, workspaces (git worktree, directory copy), crash recovery, and `resume`, `rerun`, `cancel`, `logs`, `cost`.
+
+**Agent backends**
+- Claude Code: headless (`claude -p`) and interactive (live tmux panes with hooks, an MCP result tool, limits without headless flags, steering).
+- opencode and Codex CLI runners, with structured output and session resume.
+
+**People in the loop**
+- `human.approve` gates with park/resume, approve/reject with notes, wake conditions (CLI, file, timer, GitHub review/merge), per-item history, comments that must be answered (`[whiletrue]`-prefixed replies, never resolving human threads), lessons proposed from rejections and steers that need approval, and a tmux control panel.
+
+**Integrations**
+- GitHub through the `gh` CLI: issues as items (blocked-by as dependencies, `spec:` links), PRs, sync with base, merge under a lock, review-comment replies. A file-backed fake GitHub for dry runs.
+
+**Known limits**
+- The Codex success path has not been run against a live account in CI (only its failure path and a stand-in); the real-GitHub path has been exercised only through a stand-in `gh`.
+- A watching gate keeps its parallel slot; locks are per process; interactive agents ask to trust each new worktree once.

whiletrue-0.1.0/CLAUDE.md

@@ -0,0 +1,19 @@
+# whiletrue — agent guide
+
+Local Python orchestrator that runs pipelines around coding agents. Design: `docs/architecture.md`. Plan: `docs/plan.md`. Work order: `docs/todo.md` (numbered; do items in order, tick when done).
+
+## Commands
+
+Use uv inside the devenv shell (`devenv.nix`, same format as `~/dotfiles/devenv/python`): `devenv shell -- uv run poe <task>`, or `direnv allow` once and run `poe <task>` / `pytest` directly (the venv is `.devenv/state/venv`).
+
+- `poe check` — format check, lint, typecheck, tests with coverage, docs check (run before every commit)
+- `poe test` / `poe coverage` / `poe typecheck` / `poe lint` / `poe format` / `poe docs-check`
+
+## Rules (see `docs/conventions.md`)
+
+- TDD; unit tests in `tests/unit/<pkg>/`, cross-package tests in `tests/integration/` (never beside source); coverage floor is `fail_under` in `pyproject.toml`, ratchet it up, never down.
+- Update user docs and `docs/architecture.md` in the same change as behavior.
+- `whiletrue.core` must not import git, GitHub, tmux, or any agent. Built-ins use only the public plugin API.
+- Track work in `docs/todo.md` (no GitHub issues for now). One todo item (or small group) per commit/PR. The human reviews every line before merge.
+- Never commit or push without showing the user the diff and getting explicit approval.
+- Commit trailer: `Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>`.

whiletrue-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Darius Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

whiletrue-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.5
+Name: whiletrue
+Version: 0.1.0
+Summary: Run configurable loops of agentic and deterministic steps around coding agents.
+Project-URL: Repository, https://github.com/dariussingh/whiletrue
+Project-URL: Changelog, https://github.com/dariussingh/whiletrue/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/dariussingh/whiletrue/tree/main/docs
+Author: Darius Singh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude-code,codex,opencode,orchestration,pipelines,ralph
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: common-expression-language<1,>=0.10
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: pyyaml<7,>=6
+Description-Content-Type: text/markdown
+
+# whiletrue
+
+A local, single-machine Python orchestrator that runs configurable pipelines of agentic and deterministic steps around coding agents such as Claude Code and opencode.
+
+> LangGraph builds the agent; whiletrue runs the loop around agents you already have.
+
+**Status:** M0 (core engine), M1 (control flow, composites, recipes, replay), M2 (interactive Claude Code in tmux panes) M3 (parallel items in git worktrees, crash recovery) and M4 (GitHub issues and PRs, human gates, review comments, opencode) are built in Python. `whiletrue init | validate | plan | run | resume | rerun | cancel | logs | cost | status | lock | replay | attach | panel | approve | reject | comment | history | learnings` work with the headless and interactive Claude Code runners and opencode. Start with the [reference pipeline](examples/issue-loop/README.md). See [`docs/`](docs/README.md): [getting started](docs/getting-started.md), [authoring guide](docs/authoring.md), [CLI](docs/cli.md), [reference](docs/reference.md), [architecture](docs/architecture.md), [plan](docs/plan.md), [todo](docs/todo.md).
+
+## Development
+
+See [developing.md](docs/developing.md) and, to extend whiletrue, [plugins.md](docs/plugins.md).
+
+Requires [devenv](https://devenv.sh) (or Python 3.12 + [uv](https://docs.astral.sh/uv/)).
+
+```bash
+direnv allow            # or: devenv shell
+poe check               # format check, lint, pyright, tests + coverage, docs check
+whiletrue --help        # the CLI, installed editable into .devenv/state/venv
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

whiletrue-0.1.0/README.md

@@ -0,0 +1,23 @@
+# whiletrue
+
+A local, single-machine Python orchestrator that runs configurable pipelines of agentic and deterministic steps around coding agents such as Claude Code and opencode.
+
+> LangGraph builds the agent; whiletrue runs the loop around agents you already have.
+
+**Status:** M0 (core engine), M1 (control flow, composites, recipes, replay), M2 (interactive Claude Code in tmux panes) M3 (parallel items in git worktrees, crash recovery) and M4 (GitHub issues and PRs, human gates, review comments, opencode) are built in Python. `whiletrue init | validate | plan | run | resume | rerun | cancel | logs | cost | status | lock | replay | attach | panel | approve | reject | comment | history | learnings` work with the headless and interactive Claude Code runners and opencode. Start with the [reference pipeline](examples/issue-loop/README.md). See [`docs/`](docs/README.md): [getting started](docs/getting-started.md), [authoring guide](docs/authoring.md), [CLI](docs/cli.md), [reference](docs/reference.md), [architecture](docs/architecture.md), [plan](docs/plan.md), [todo](docs/todo.md).
+
+## Development
+
+See [developing.md](docs/developing.md) and, to extend whiletrue, [plugins.md](docs/plugins.md).
+
+Requires [devenv](https://devenv.sh) (or Python 3.12 + [uv](https://docs.astral.sh/uv/)).
+
+```bash
+direnv allow            # or: devenv shell
+poe check               # format check, lint, pyright, tests + coverage, docs check
+whiletrue --help        # the CLI, installed editable into .devenv/state/venv
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

whiletrue-0.1.0/devenv.lock

@@ -0,0 +1,131 @@
+{
+  "nodes": {
+    "devenv": {
+      "locked": {
+        "dir": "src/modules",
+        "lastModified": 1792016320,
+        "owner": "cachix",
+        "repo": "devenv",
+        "rev": "03582faca930c95cb28d5d3cd2370325b0072fde",
+        "type": "github"
+      },
+      "original": {
+        "dir": "src/modules",
+        "owner": "cachix",
+        "repo": "devenv",
+        "type": "github"
+      }
+    },
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1767039857,
+        "owner": "NixOS",
+        "repo": "flake-compat",
+        "rev": "5edf11c44bc78a0d334f6334cdaf7d60d732daab",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "flake-compat_2": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1767039857,
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "5edf11c44bc78a0d334f6334cdaf7d60d732daab",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "git-hooks": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1791909798,
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "rev": "1ba1dbfe28738c9a71c266be6efa5b89e75491a9",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1791637130,
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "ca1659429c950a11a565b5764e37a1b704e17ec8",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-python": {
+      "inputs": {
+        "flake-compat": "flake-compat_2",
+        "nixpkgs": "nixpkgs_2"
+      },
+      "locked": {
+        "lastModified": 1791208659,
+        "owner": "cachix",
+        "repo": "nixpkgs-python",
+        "rev": "5821ac5267b0dc89e48705407206e3c88ee3e0ad",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "nixpkgs-python",
+        "type": "github"
+      }
+    },
+    "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1782847189,
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "b6018f87da91d19d0ab4cf979885689b469cdd41",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-25.11",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "devenv": "devenv",
+        "git-hooks": "git-hooks",
+        "nixpkgs": "nixpkgs",
+        "nixpkgs-python": "nixpkgs-python",
+        "pre-commit-hooks": [
+          "git-hooks"
+        ]
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

whiletrue-0.1.0/devenv.nix

@@ -0,0 +1,28 @@
+{
+  pkgs,
+  ...
+}:
+{
+  packages = with pkgs; [
+    git
+    gh
+    tmux
+  ];
+
+  languages.python = {
+    enable = true;
+    version = "3.12";
+    uv = {
+      enable = true;
+      sync.enable = true;
+      sync.allGroups = true;
+    };
+  };
+
+  scripts.check.exec = "uv run poe check";
+
+  enterShell = ''
+    . .devenv/state/venv/bin/activate
+    echo "whiletrue devenv: $(python --version), uv $(uv --version | cut -d' ' -f2)"
+  '';
+}

whiletrue-0.1.0/devenv.yaml

@@ -0,0 +1,13 @@
+inputs:
+  nixpkgs:
+    url: github:NixOS/nixpkgs/nixpkgs-unstable
+  nixpkgs-python:
+    url: github:cachix/nixpkgs-python
+
+# If you're willing to use a package that's vulnerable
+# permittedInsecurePackages:
+#  - "openssl-1.1.1w"
+
+# If you have more than one devenv you can merge them
+#imports:
+# - ./backend

whiletrue-0.1.0/docs/README.md

@@ -0,0 +1,18 @@
+# whiletrue docs
+
+| Doc                                    | Purpose                                                                           |
+| -------------------------------------- | --------------------------------------------------------------------------------- |
+| [architecture.md](architecture.md)     | Full design: core model, runtime, state, agents, human gates, packages            |
+| [getting-started.md](getting-started.md) | User guide: install, first loop, commands, exit codes, safety defaults          |
+| [authoring.md](authoring.md)           | Authoring guide: pipelines, composites, agents, choosing a backend                |
+| [cli.md](cli.md)                       | CLI reference: every command, option, exit code and environment variable          |
+| [reference.md](reference.md)           | User reference: modules, control flow, expressions, composites, recipes, replay   |
+| [plugins.md](plugins.md)               | Extending whiletrue: modules, strategies, runners, caps, entry points              |
+| [developing.md](developing.md)         | Contributing: setup, layout, run flow, workflow                                    |
+| [plan.md](plan.md)                     | Implementation plan: milestones M0–M4, dependencies, exit criteria, risks, spikes |
+| [todo.md](todo.md)                     | Numbered, ordered implementation checklist (work top to bottom)                   |
+| [open-questions.md](open-questions.md) | Undecided design questions, each tied to the milestone that forces the decision   |
+| [spike-interactive.md](spike-interactive.md) | Findings: plugin hooks and MCP in interactive Claude Code (OQ-1)               |
+| [conventions.md](conventions.md)       | Engineering conventions, test and docs rules (the non-negotiables made concrete)  |
+
+Non-negotiables (every change must honor them): human keeps context; maximal test coverage; user and architecture docs stay current; human is accountable for every line.