tazuna 0.3.0__tar.gz

tazuna-0.3.0/.cursor/rules/project.mdc

@@ -0,0 +1,61 @@
+---
+description: Project contract (generated from PROJECT.md)
+alwaysApply: true
+---
+<!-- GENERATED-FROM: PROJECT.md by tazuna — do not edit. Edit PROJECT.md and run `tazuna render`. -->
+
+# tazuna — PROJECT.md
+
+<!-- Single source of project policy. CLAUDE.md, AGENTS.md and .cursor/rules/project.mdc are
+     GENERATED from this file by `tazuna render`. Edit here, then re-render. -->
+
+## Purpose and current state
+
+tazuna is a provider-neutral control plane for AI coding agents: one policy file rendered into every harness, static role-based routing across provider CLIs, a uniform HANDOFF + exit-code result contract, reproducible evals, and diagnostics. This repository dogfoods itself: the files you are reading were rendered by `tazuna render`. Version 0.1.0, alpha.
+
+## Stack
+
+| Item | Value |
+|---|---|
+| Language | Python 3.11+, standard library only at runtime (tomllib, subprocess, argparse) |
+| Layout | `src/tazuna/` package (`cli.py`, `config.py`, `render.py`, `routing.py`, `run.py`, `handoff.py`, `evals.py`, `doctor.py`, `guard.py`), package data in `providers/*.toml`, `targets.toml`, `templates/` |
+| Tests | pytest in `tests/`; shims only, never a real provider |
+| Docs | `docs/*.md`; `README.md` is the front page |
+| Extension | `packs/` (see `docs/packs.md`) |
+| Evals | `evals/suites/smoke` (offline) |
+
+## Commands
+
+| Purpose | Command |
+|---|---|
+| Install for development | `uv venv && uv pip install -e '.[dev]'` |
+| Test | `.venv/bin/pytest` |
+| Lint | `.venv/bin/ruff check src tests` |
+| Self-check the contract layer | `tazuna render --check && tazuna doctor` |
+| Offline eval | `tazuna eval run evals/suites/smoke --role dry` |
+
+## Quality gate (required before merge)
+
+- [ ] `pytest` passes on Linux and macOS (CI matrix)
+- [ ] `ruff check src tests` is clean
+- [ ] `tazuna render --check` and `tazuna doctor` pass in this repository
+- [ ] User-visible changes are in `CHANGELOG.md` and the relevant `docs/*.md`
+- [ ] A provider definition change comes with an argv test against a shim
+
+## Do not
+
+- Add runtime dependencies. `tomllib` and the standard library are enough.
+- Read, write, or log `.env`, `.env.*`, `secrets/**`, or credential files.
+- Edit generated files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/project.mdc`); edit `PROJECT.md` and run `tazuna render`.
+- Add flags to provider definitions that disable a harness's approvals or sandbox (`--dangerously-*`, `--yolo`, `--force`); `run.py` rejects them.
+- Let tests reach a real provider CLI; use the shims in `tests/conftest.py`.
+
+## Known pitfalls
+
+- `is_generated` looks at the first eight lines; a target whose frontmatter is longer will be treated as hand-written. Keep `frontmatter` short.
+- Exit codes are the automation contract. The provider's self-report refines `status` only; never let it change the exit code.
+- Provider CLIs change flags between releases. Verify with `tazuna run --role X --dry-run` after upgrading a CLI, and keep `experimental = true` on definitions nobody has run end to end.
+
+## References
+
+- Architecture: `docs/architecture.md` · Security model: `docs/security.md` · Result contract: `docs/handoff.md`

tazuna-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e '.[dev]'
+      - run: ruff check src tests
+      - run: pytest
+      - name: contract self-check
+        run: |
+          tazuna render --check
+          tazuna doctor
+          tazuna eval run evals/suites/smoke --role dry

tazuna-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: release
+
+# Builds the sdist and wheel for every published GitHub release and uploads them to PyPI
+# through trusted publishing (no API token stored in the repository).
+#
+# One-time setup by the repository owner, after which the `publish` job runs automatically:
+#   1. On PyPI: add a pending GitHub publisher for project "tazuna" (a new name, not a rename of
+#      "agentplane", so the publisher set up for agentplane does not carry over)
+#      (owner KK-18-dot, repository tazuna, workflow release.yml, environment pypi).
+#   2. On GitHub: Settings → Environments → create "pypi".
+#   3. On GitHub: Settings → Variables → Actions → PYPI_TRUSTED_PUBLISHER = true.
+# Until step 3 is done the publish job is skipped, so a release never fails on a missing publisher.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - name: smoke-test the wheel in a clean environment
+        run: |
+          python -m venv /tmp/v
+          /tmp/v/bin/pip install -q dist/*.whl
+          /tmp/v/bin/tazuna --version
+          /tmp/v/bin/tazuna init --dir /tmp/p
+          /tmp/v/bin/tazuna render --dir /tmp/p
+          /tmp/v/bin/tazuna run --role dry --dir /tmp/p --quiet "release smoke"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    if: vars.PYPI_TRUSTED_PUBLISHER == 'true'
+    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

tazuna-0.3.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+# local secrets and environment files must never be committed
+.env
+.env.*
+!.env.example
+secrets/
+# eval results are local artifacts unless deliberately committed as baselines
+evals/results/
+# the owner's local work ledger (dev-platform backlog.sh / board read it from disk)
+BACKLOG.md

tazuna-0.3.0/AGENTS.md

@@ -0,0 +1,57 @@
+<!-- GENERATED-FROM: PROJECT.md by tazuna — do not edit. Edit PROJECT.md and run `tazuna render`. -->
+
+# tazuna — PROJECT.md
+
+<!-- Single source of project policy. CLAUDE.md, AGENTS.md and .cursor/rules/project.mdc are
+     GENERATED from this file by `tazuna render`. Edit here, then re-render. -->
+
+## Purpose and current state
+
+tazuna is a provider-neutral control plane for AI coding agents: one policy file rendered into every harness, static role-based routing across provider CLIs, a uniform HANDOFF + exit-code result contract, reproducible evals, and diagnostics. This repository dogfoods itself: the files you are reading were rendered by `tazuna render`. Version 0.1.0, alpha.
+
+## Stack
+
+| Item | Value |
+|---|---|
+| Language | Python 3.11+, standard library only at runtime (tomllib, subprocess, argparse) |
+| Layout | `src/tazuna/` package (`cli.py`, `config.py`, `render.py`, `routing.py`, `run.py`, `handoff.py`, `evals.py`, `doctor.py`, `guard.py`), package data in `providers/*.toml`, `targets.toml`, `templates/` |
+| Tests | pytest in `tests/`; shims only, never a real provider |
+| Docs | `docs/*.md`; `README.md` is the front page |
+| Extension | `packs/` (see `docs/packs.md`) |
+| Evals | `evals/suites/smoke` (offline) |
+
+## Commands
+
+| Purpose | Command |
+|---|---|
+| Install for development | `uv venv && uv pip install -e '.[dev]'` |
+| Test | `.venv/bin/pytest` |
+| Lint | `.venv/bin/ruff check src tests` |
+| Self-check the contract layer | `tazuna render --check && tazuna doctor` |
+| Offline eval | `tazuna eval run evals/suites/smoke --role dry` |
+
+## Quality gate (required before merge)
+
+- [ ] `pytest` passes on Linux and macOS (CI matrix)
+- [ ] `ruff check src tests` is clean
+- [ ] `tazuna render --check` and `tazuna doctor` pass in this repository
+- [ ] User-visible changes are in `CHANGELOG.md` and the relevant `docs/*.md`
+- [ ] A provider definition change comes with an argv test against a shim
+
+## Do not
+
+- Add runtime dependencies. `tomllib` and the standard library are enough.
+- Read, write, or log `.env`, `.env.*`, `secrets/**`, or credential files.
+- Edit generated files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/project.mdc`); edit `PROJECT.md` and run `tazuna render`.
+- Add flags to provider definitions that disable a harness's approvals or sandbox (`--dangerously-*`, `--yolo`, `--force`); `run.py` rejects them.
+- Let tests reach a real provider CLI; use the shims in `tests/conftest.py`.
+
+## Known pitfalls
+
+- `is_generated` looks at the first eight lines; a target whose frontmatter is longer will be treated as hand-written. Keep `frontmatter` short.
+- Exit codes are the automation contract. The provider's self-report refines `status` only; never let it change the exit code.
+- Provider CLIs change flags between releases. Verify with `tazuna run --role X --dry-run` after upgrading a CLI, and keep `experimental = true` on definitions nobody has run end to end.
+
+## References
+
+- Architecture: `docs/architecture.md` · Security model: `docs/security.md` · Result contract: `docs/handoff.md`

tazuna-0.3.0/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+## 0.3.0 — 2026-09-26
+
+### Upgrade notes
+
+- The project is renamed from `agentplane` to `tazuna` (手綱, "the reins"). There is no compatibility layer: the package, the command, the module, the config file, the environment variables and the self-report line all change, and the old names are not read. To move a project:
+  - `pipx uninstall agentplane && pipx install tazuna` (or the same with pip).
+  - Rename `agentplane.toml` to `tazuna.toml`, a `.agentplane/` directory to `.tazuna/`, and `~/.config/agentplane/` to `~/.config/tazuna/`. `tazuna doctor` warns while any of these is left, and a missing `tazuna.toml` next to an `agentplane.toml` is reported as a rename, not as "run init".
+  - Replace `agentplane` with `tazuna` in CI, Makefiles, scripts and hook commands (`tazuna guard --hook claude`), and `AGENTPLANE_` with `TAZUNA_` in scripts and eval `check.sh` files.
+  - Replace `AGENTPLANE-STATUS:` with `TAZUNA-STATUS:` wherever it is written or matched: policy text that tells agents how to report, pack provider scripts, `[providers.mock] response`, and eval `expect_output_regex`. An old line is not recognized, so a run that reported BLOCKED under the old name is recorded as `done`.
+  - Run `tazuna render` and commit the result. The generated header now names tazuna, so `render --check` reports drift until you do; the files themselves are still recognized as generated, because the marker does not carry the tool name.
+- The run ledger moves to `$XDG_STATE_HOME/tazuna`; the old ledger stays where it was.
+
+### Fixed
+
+- `agentplane guard --hook claude` and `agentplane guard --print-hook` failed with "unrecognized arguments" and exit 2. The hook command that `--print-hook` and the `guard` docstring describe would therefore have made Claude Code block every Edit / Write / MultiEdit call. `--hook` and `--print-hook` are now real options, the paths form is unchanged, and tests call `guard` through the CLI.
+- An unknown `--hook` value no longer exits 2 (which a harness reads as a block); guard warns on stderr and allows, as the rest of the hook does.
+
+### Added
+
+- The quickstart shows how to install the Claude Code hook with `tazuna guard --print-hook`.
+
+## 0.2.0 — 2026-09-17
+
+### Upgrade notes
+
+- The forbidden-flag check is stricter (see Fixed). A provider table that passed `-f`, `-y`, `--force=…` or a `bypassPermissions` / `danger-full-access` value is now refused with exit 3, and `doctor` names it.
+- New exit codes 130 / 143 and status `cancelled`. Scripts that treated any non-zero exit as a provider failure keep working; scripts that match statuses should add `cancelled`.
+- The ledger gains `parent`; `command` holds `<task>` for argument-passing providers. Existing fields keep their meaning.
+
+### Fixed
+
+- `changed` no longer misses real changes. The before/after snapshot now records `HEAD` and a content hash per dirty path (untracked directories expanded), so a second edit to a file that was already modified, a new file inside an already-untracked directory, and commits made by the provider (`commits: a..b (N)` plus `committed <S> <path>` lines) all show up. Paths that were dirty before and are clean now are listed too. Entries stay plain strings in the ledger.
+- Run ids carry a random suffix and log files are created exclusively (`O_EXCL`), so eval trials started by one process within the same second no longer share, and overwrite, one log.
+- A fallback no longer runs a `read_only = true` fallback role writable when the original route was writable. Fallback can only tighten read-only.
+- Cancelling agentplane no longer leaves the provider running. SIGINT / SIGTERM / SIGHUP stop the provider's process group, and the run is still recorded (HANDOFF + ledger) with the new status `cancelled` and exit code 130 (SIGINT) or 143 (SIGTERM, SIGHUP). Cancelled runs never trigger the fallback. The task is now fed to the provider's stdin from a thread, so a provider that does not read a large task can no longer block the timeout.
+- The forbidden-flag check matched exact strings only. It now also refuses `--dangerously-*=…`, `--force=…`, the short forms `-f` / `-y`, and the values `bypassPermissions`, `danger-full-access` and `yolo` as separate arguments or after `=` (covering `--permission-mode bypassPermissions`, `--sandbox=danger-full-access`, `-c sandbox_mode=danger-full-access`, `--approval-mode yolo`). Task text is no longer checked, so a task reading `--force` is not refused. `doctor` warns about such flags in any provider table.
+- The ledger no longer stores the full task for `task_via = "arg"` providers (cursor, gemini): `command` records `<task>` in its place, and `task_head` is masked like the HANDOFF. Ledger lines are appended with a single `os.write` on an `O_APPEND` descriptor.
+- State files were world-readable. The state directory, `logs/` and `evals/` are now created 0700, log files and `runs.jsonl` 0600, without touching the umask the provider inherits. `doctor` warns when an existing state directory or ledger is open to group/other and prints the `chmod` fix. Token shapes are masked in the log on disk after each run.
+- `eval report` now implements the documented rule: runs with status `quota-exhausted`, `auth-required` or `cancelled` are excluded from pass rates and counted in a new `excluded` column. `timeout` still counts as a failure, and `docs/evals.md` now says so.
+- Ctrl-C during `eval run` stopped only the current trial and the suite went on, with the cancelled trial counted as a failure. A cancelled trial now stops the suite (exit 130 / 143) after its row and the report are written, even when its HANDOFF could not be written.
+- A task that is not valid UTF-8 crashed after the provider had started and left no ledger row (and, for stdin providers, a provider waiting until the timeout). It is now refused before launch with exit 2 (so is a task containing a NUL byte, which crashed arg-passing providers), whether it came as an argument, on stdin or through `--task-file` (which printed a traceback). Any error while writing the HANDOFF now ends as `handoff-write-failed` with a ledger row, and the provider's stdin is always closed.
+- A provider's short final lines, including its `AGENTPLANE-STATUS` line, could be lost when a process it started detached and kept the output pipe open. Output is now logged as soon as it is readable.
+- A signal that arrived while the HANDOFF and ledger row were being written could kill agentplane between the two. Both are now written first. When a signal stops a run before its fallback, the HANDOFF describes that run instead of keeping an older file.
+
+### Security
+
+Findings from a review of the changes above, fixed before release:
+
+- The git commands behind `changed`, `doctor` and `status` no longer run commands a provider planted in the repository (`core.fsmonitor`, filter drivers, the post-index-change hook), and they get the allowlisted environment instead of agentplane's own. A filter driver whose name cannot be overridden makes the snapshot refuse, with a note in `changed`.
+- File names in `changed` are quoted with git-style escapes when they contain control or format characters, quotes or backslashes, so a file name can no longer add sections to the HANDOFF. A trailing CR in a name is hashed correctly.
+- `changed` also lists newly set `skip-worktree` / `assume-unchanged` flags and changes to git's `config`, `info/exclude`, `info/attributes` and `hooks/*`.
+- With a nested `--out` (`--out dir/a/b/HANDOFF.md`), a provider that replaced `dir/a` with a symlink could make agentplane write the HANDOFF outside `--dir`. The output directory is now opened one component at a time from `--dir` without following symlinks (present since 0.1.0).
+- A failing or slow snapshot (for example a huge file) no longer loses the run: files above 8 MiB are fingerprinted by size and mtime, FIFOs and devices are never read, and any snapshot error becomes a note in `changed`.
+- A signal that arrives while output is still being collected cancels the run (no fallback). Processes the provider left holding its output are killed with its process group when the run is over, and later output is dropped instead of reaching the log unmasked.
+- The forbidden-flag check also splits at every `=` (`--config=sandbox_mode=danger-full-access`), ignores surrounding whitespace, refuses any flag or config key containing `dangerously` (`--allow-dangerously-skip-permissions`), and refuses `bypassPermissions` / `danger-full-access` anywhere in an element.
+- The empty MCP config handed to Claude Code is re-checked before each run, model ids may no longer start with `-`, `doctor` warns when the state directory belongs to another user, `check.sh` failure reasons are masked, and `eval report --fail-on-regression` names the baseline cases it could not compare.
+
+### Added
+
+- Run lineage: the ledger has a `parent` field, taken from `AGENTPLANE_PARENT` when it is a plain token (otherwise ignored with a warning). agentplane sets `AGENTPLANE_PARENT` to the current run id for every provider it launches, so nested delegation is traceable from the ledger, and scripts or CI can set it to their own id.
+- `agentplane run --json` prints the final ledger record as one JSON object on stdout (no provider echo, no `HANDOFF:` line).
+- `docs/handoff.md` documents the ledger fields as a stable interface and the `status` values as a closed vocabulary.
+- `agentplane eval report RESULTS --baseline BASE --fail-on-regression` exits 1 when a case present in both files has a lower pass rate than the baseline, or when the results are incomplete (a cancelled or excluded trial, or a missing baseline case), for CI. A subset run (`--only`) against a full baseline, or a run during a provider outage, therefore fails the gate.
+- Eval result rows carry `run_id`, the ledger id of the run.
+- `max_bytes` on render targets. The built-in `codex` target sets 32768, the size at which Codex CLI stops reading `AGENTS.md`. An oversized target is still written with a warning, fails `render --check` as `too-large`, and is a `doctor` WARN.
+
+### Internal
+
+- The git snapshot and the hardened git helper moved from `agentplane.run` to `agentplane.gitstate`. The Python modules are not a stable interface; the CLI, HANDOFF and ledger are.
+
+## 0.1.0 — 2026-09-13
+
+First public release, available on PyPI (`pipx install agentplane`).
+
+- `init`, `render` (`--check`, `--adopt`, `--force`, appendices, `{{model:…}}` expansion), built-in targets for Claude Code, Codex/AGENTS.md, Cursor, Gemini CLI, Copilot, Windsurf, Cline.
+- `run` with role-based routing, explicit overrides, allowlisted environment, timeout, safety boundaries, typed self-report, failure classification, one-shot fallback, HANDOFF.md, JSONL ledger.
+- Built-in providers: claude, codex, cursor, gemini (experimental), ollama, mock.
+- `routes`, `doctor` (OK/WARN/NOTE), `status`, `runs`, `packs`, `guard` (Claude Code hook adapter).
+- `eval run` / `eval report` with fixture suites, code graders, signed baseline diffs; bundled offline smoke suite.
+- Packs: directories of the same TOML tables, with `{pack_dir}` and pack-relative appendices.

tazuna-0.3.0/CLAUDE.md

@@ -0,0 +1,64 @@
+<!-- GENERATED-FROM: PROJECT.md by tazuna — do not edit. Edit PROJECT.md and run `tazuna render`. -->
+
+# tazuna — PROJECT.md
+
+<!-- Single source of project policy. CLAUDE.md, AGENTS.md and .cursor/rules/project.mdc are
+     GENERATED from this file by `tazuna render`. Edit here, then re-render. -->
+
+## Purpose and current state
+
+tazuna is a provider-neutral control plane for AI coding agents: one policy file rendered into every harness, static role-based routing across provider CLIs, a uniform HANDOFF + exit-code result contract, reproducible evals, and diagnostics. This repository dogfoods itself: the files you are reading were rendered by `tazuna render`. Version 0.1.0, alpha.
+
+## Stack
+
+| Item | Value |
+|---|---|
+| Language | Python 3.11+, standard library only at runtime (tomllib, subprocess, argparse) |
+| Layout | `src/tazuna/` package (`cli.py`, `config.py`, `render.py`, `routing.py`, `run.py`, `handoff.py`, `evals.py`, `doctor.py`, `guard.py`), package data in `providers/*.toml`, `targets.toml`, `templates/` |
+| Tests | pytest in `tests/`; shims only, never a real provider |
+| Docs | `docs/*.md`; `README.md` is the front page |
+| Extension | `packs/` (see `docs/packs.md`) |
+| Evals | `evals/suites/smoke` (offline) |
+
+## Commands
+
+| Purpose | Command |
+|---|---|
+| Install for development | `uv venv && uv pip install -e '.[dev]'` |
+| Test | `.venv/bin/pytest` |
+| Lint | `.venv/bin/ruff check src tests` |
+| Self-check the contract layer | `tazuna render --check && tazuna doctor` |
+| Offline eval | `tazuna eval run evals/suites/smoke --role dry` |
+
+## Quality gate (required before merge)
+
+- [ ] `pytest` passes on Linux and macOS (CI matrix)
+- [ ] `ruff check src tests` is clean
+- [ ] `tazuna render --check` and `tazuna doctor` pass in this repository
+- [ ] User-visible changes are in `CHANGELOG.md` and the relevant `docs/*.md`
+- [ ] A provider definition change comes with an argv test against a shim
+
+## Do not
+
+- Add runtime dependencies. `tomllib` and the standard library are enough.
+- Read, write, or log `.env`, `.env.*`, `secrets/**`, or credential files.
+- Edit generated files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/project.mdc`); edit `PROJECT.md` and run `tazuna render`.
+- Add flags to provider definitions that disable a harness's approvals or sandbox (`--dangerously-*`, `--yolo`, `--force`); `run.py` rejects them.
+- Let tests reach a real provider CLI; use the shims in `tests/conftest.py`.
+
+## Known pitfalls
+
+- `is_generated` looks at the first eight lines; a target whose frontmatter is longer will be treated as hand-written. Keep `frontmatter` short.
+- Exit codes are the automation contract. The provider's self-report refines `status` only; never let it change the exit code.
+- Provider CLIs change flags between releases. Verify with `tazuna run --role X --dry-run` after upgrading a CLI, and keep `experimental = true` on definitions nobody has run end to end.
+
+## References
+
+- Architecture: `docs/architecture.md` · Security model: `docs/security.md` · Result contract: `docs/handoff.md`
+
+<!-- appendix: claude.md -->
+
+## Claude Code specifics (from example-pack)
+
+- This section is appended to `CLAUDE.md` only; other targets do not see it.
+- Put harness-specific instructions here (tool preferences, slash commands, hook expectations) and keep `PROJECT.md` harness-neutral.

tazuna-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+## Setup
+
+```bash
+git clone https://github.com/KK-18-dot/tazuna
+cd tazuna
+uv venv && uv pip install -e '.[dev]'      # or: python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest
+.venv/bin/ruff check src tests
+```
+
+Tests never touch a real provider: they run in a throwaway HOME with a PATH that contains only recorded shims. Keep it that way. If you add a provider definition, add a test that asserts the exact argv the shim receives.
+
+## What fits
+
+tazuna does four things: render policy, route roles, record results, grade evals. Contributions that make those four smaller, safer, or clearer are welcome. Things that belong elsewhere:
+
+- skill libraries, agent personas, workflow engines (put them in a pack, or in your harness)
+- schedulers, daemons, multiplexer integrations
+- anything that requires a runtime dependency
+
+## Provider definitions
+
+Built-in providers live in `src/tazuna/providers/*.toml`. When a CLI changes its flags, update the table, note the CLI version in the commit message, and add or adjust the argv test. Mark a provider `experimental = true` until someone has run the smoke suite against it end to end.
+
+## Releasing
+
+1. Bump `version` in `pyproject.toml` and `__version__` in `src/tazuna/__init__.py`; add a `CHANGELOG.md` entry.
+2. `git tag -a vX.Y.Z -m "vX.Y.Z" && git push --tags`, then create a GitHub release from the tag.
+3. `.github/workflows/release.yml` builds the sdist and wheel, smoke-tests the wheel in a clean environment, and publishes both to PyPI through trusted publishing with provenance attestations. The `pypi` environment is configured. The trusted publisher was set up for the old name `agentplane` and must be added again for `tazuna` before the first release under the new name (see the comment at the top of `release.yml`). The repository variable `PYPI_TRUSTED_PUBLISHER` (`true`) gates the publish job.
+4. Check the result: `pipx install --force tazuna==X.Y.Z && tazuna --version` (or the same with `python -m pip` in a fresh virtual environment).
+
+## Commits and pull requests
+
+- `type: description` (feat / fix / docs / test / refactor / chore). The body says why, including alternatives you rejected.
+- Run `pytest` and `ruff check` before opening a PR; CI runs both on Linux and macOS.
+- Document user-visible changes in `CHANGELOG.md`.

tazuna-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tazuna contributors
+
+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.

tazuna-0.3.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: tazuna
+Version: 0.3.0
+Summary: Define project policy once, render it into every agent harness, route work across providers, and get auditable results.
+Project-URL: Homepage, https://github.com/KK-18-dot/tazuna
+Project-URL: Issues, https://github.com/KK-18-dot/tazuna/issues
+Author: tazuna contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents-md,ai-agents,claude-code,codex,cursor,evals,routing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tazuna
+
+[![PyPI](https://img.shields.io/pypi/v/tazuna)](https://pypi.org/project/tazuna/) [![Python](https://img.shields.io/pypi/pyversions/tazuna)](https://pypi.org/project/tazuna/)
+
+**Define project policy once. Render it into every agent harness. Route work across providers. Get auditable results.**
+
+*Tazuna* (手綱) is Japanese for the reins: one pair of hands steering several horses. Versions up to 0.2.0 were published as `agentplane`; see the [changelog](https://github.com/KK-18-dot/tazuna/blob/main/CHANGELOG.md) for the rename.
+
+tazuna is a small, provider-neutral control plane for teams that use more than one AI coding agent (Claude Code, Codex, Cursor, Gemini CLI, local models, or anything with a headless CLI). It does four things and nothing else:
+
+| | What | Command |
+|---|---|---|
+| 1 | **One policy, many harnesses.** `PROJECT.md` is the single source; `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/project.mdc` (and more) are generated from it and guarded against hand edits. | `tazuna render` |
+| 2 | **Understandable routing.** A *role* is a named row in `tazuna.toml`: provider, model, effort, timeout, read-only, fallback. Nothing is chosen by heuristics at runtime. | `tazuna routes` |
+| 3 | **Auditable execution.** Every delegated task ends in a `HANDOFF.md` built from measured facts (git diff, exit code, duration, effective model), a typed status, and a JSONL ledger. | `tazuna run` |
+| 4 | **Reproducible evals and diagnostics.** Fixture directories run through the same path and are graded deterministically; `doctor` says what is broken vs. merely optional. | `tazuna eval`, `tazuna doctor` |
+
+It is *not* a skill library, an agent framework, or a swarm runtime. It sits under those and gives them one policy file, one routing table, and one result contract.
+
+## Install
+
+Python 3.11+ and git. No other runtime dependencies.
+
+tazuna is published on [PyPI](https://pypi.org/project/tazuna/). Install the CLI into its own environment with pipx:
+
+```bash
+pipx install tazuna
+tazuna --version
+```
+
+If you do not use pipx, pip works too (inside a virtual environment):
+
+```bash
+python -m pip install tazuna
+```
+
+`uv tool install tazuna` is equivalent to the pipx command. Release artifacts on PyPI are uploaded from GitHub Actions through trusted publishing and carry provenance attestations. To work on tazuna itself, install from a checkout as described in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Provider CLIs are optional. Install whichever you use (`claude`, `codex`, `cursor-agent`, `gemini`, `ollama`); tazuna detects them and works offline with a built-in mock provider when none is present.
+
+### Use it with whatever plan you have
+
+tazuna never talks to a model API itself. It launches the provider CLIs you already have, under the login and billing you already use, so pick the setup that matches your contract:
+
+| You have | Use | Notes |
+|---|---|---|
+| A subscription that includes a CLI (Claude Pro/Max → `claude`, ChatGPT Plus/Pro → `codex`, Cursor → `cursor-agent`, Google AI → `gemini`) | roles on that provider | the CLI's own login is used; no API key is needed or forwarded |
+| API keys instead of a subscription | the same CLIs configured for API billing, per each vendor's docs | keys stay in the CLI's own config; tazuna's environment allowlist does not forward them |
+| Several of the above | one role per provider, `fallback` between them | `routes` shows which provider each role bills |
+| No paid plan, or private data | `ollama` with a local model, `read_only` | offline, nothing leaves the machine |
+| Nothing yet | the `mock` provider (`--role dry`) | exercises the whole pipeline without a model |
+
+The model ids written by `tazuna init` are examples. Replace them with the ids your plan actually enables (each CLI can list its models), keep personal choices in `~/.config/tazuna/config.toml`, and check the resolved command with `tazuna run --role X --dry-run` before spending quota.
+
+## Quickstart (5 minutes)
+
+```bash
+cd your-project
+tazuna init                  # writes tazuna.toml + PROJECT.md, roles for the CLIs it finds
+$EDITOR PROJECT.md           # describe the project once: purpose, stack, commands, quality gate, do-nots
+tazuna render                # -> CLAUDE.md, AGENTS.md, .cursor/rules/project.mdc
+tazuna routes                # what each role resolves to, and whether its provider is installed
+tazuna doctor                # OK / WARN / NOTE; exit 1 only on real problems
+```
+
+Delegate a task and read the result:
+
+```bash
+tazuna run --role dry "Summarize the repo layout in five bullets"      # offline mock, always works
+tazuna run --role review --read-only "Review src/ for missing error handling"
+tazuna run --role impl --task-file PLAN.md --timeout 1200
+cat HANDOFF.md               # status, changed files, verification facts, provider output tail
+tazuna runs                  # ledger of every run
+```
+
+Keep generated files honest in CI:
+
+```bash
+tazuna render --check        # exit 1 on drift
+tazuna doctor                # exit 1 on WARN
+```
+
+Run the bundled offline eval suite:
+
+```bash
+tazuna eval run evals/suites/smoke --role dry
+```
+
+## How it fits together
+
+```
+PROJECT.md ──render──▶ CLAUDE.md / AGENTS.md / .cursor/rules/project.mdc / GEMINI.md / …
+     ▲                      (generated marker; `guard` and `render --check` protect them)
+     │
+tazuna.toml ── roles ──▶ run --role X ──▶ provider CLI (env allowlist, timeout, sandbox flags)
+     │                                            │
+     └── providers (built-in + packs + user)      ▼
+                                       HANDOFF.md + runs.jsonl + log   ←── evals grade these
+```
+
+- **Policy layer**: `PROJECT.md` (+ optional per-target appendices in `.tazuna/appendix/`). Model aliases `{{model:NAME}}` expand from `[models]`.
+- **Routing layer**: `[roles.*]` in `tazuna.toml`; personal provider choices go in `~/.config/tazuna/config.toml` and never into the repo.
+- **Execution layer**: `run` launches the provider headless with an allowlisted environment, a timeout, and the provider's own sandbox flags; it never passes flags that disable a harness's approvals.
+- **Result contract**: exit code `0 done · 1 failed · 2 usage · 3 safety boundary · 4 empty output · 124 timeout · 130/143 cancelled`, plus the provider's typed self-report (`DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, `NEEDS_CONTEXT`) read only from its last line.
+- **Extension**: packs (`pack.toml`) add providers, targets, roles, and appendices. See `packs/`.
+
+Full docs: [docs/quickstart.md](docs/quickstart.md) · [docs/configuration.md](docs/configuration.md) · [docs/routing.md](docs/routing.md) · [docs/handoff.md](docs/handoff.md) · [docs/evals.md](docs/evals.md) · [docs/packs.md](docs/packs.md) · [docs/architecture.md](docs/architecture.md) · [docs/security.md](docs/security.md)
+
+## Status
+
+0.3.0, alpha. The Claude Code, Codex, and Cursor provider definitions mirror flags used in production; Gemini CLI is marked experimental. Provider CLIs change their flags; if one breaks, override the provider table in your user config and open an issue.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tazuna-0.3.0/PROJECT.md

@@ -0,0 +1,55 @@
+# tazuna — PROJECT.md
+
+<!-- Single source of project policy. CLAUDE.md, AGENTS.md and .cursor/rules/project.mdc are
+     GENERATED from this file by `tazuna render`. Edit here, then re-render. -->
+
+## Purpose and current state
+
+tazuna is a provider-neutral control plane for AI coding agents: one policy file rendered into every harness, static role-based routing across provider CLIs, a uniform HANDOFF + exit-code result contract, reproducible evals, and diagnostics. This repository dogfoods itself: the files you are reading were rendered by `tazuna render`. Version 0.1.0, alpha.
+
+## Stack
+
+| Item | Value |
+|---|---|
+| Language | Python 3.11+, standard library only at runtime (tomllib, subprocess, argparse) |
+| Layout | `src/tazuna/` package (`cli.py`, `config.py`, `render.py`, `routing.py`, `run.py`, `handoff.py`, `evals.py`, `doctor.py`, `guard.py`), package data in `providers/*.toml`, `targets.toml`, `templates/` |
+| Tests | pytest in `tests/`; shims only, never a real provider |
+| Docs | `docs/*.md`; `README.md` is the front page |
+| Extension | `packs/` (see `docs/packs.md`) |
+| Evals | `evals/suites/smoke` (offline) |
+
+## Commands
+
+| Purpose | Command |
+|---|---|
+| Install for development | `uv venv && uv pip install -e '.[dev]'` |
+| Test | `.venv/bin/pytest` |
+| Lint | `.venv/bin/ruff check src tests` |
+| Self-check the contract layer | `tazuna render --check && tazuna doctor` |
+| Offline eval | `tazuna eval run evals/suites/smoke --role dry` |
+
+## Quality gate (required before merge)
+
+- [ ] `pytest` passes on Linux and macOS (CI matrix)
+- [ ] `ruff check src tests` is clean
+- [ ] `tazuna render --check` and `tazuna doctor` pass in this repository
+- [ ] User-visible changes are in `CHANGELOG.md` and the relevant `docs/*.md`
+- [ ] A provider definition change comes with an argv test against a shim
+
+## Do not
+
+- Add runtime dependencies. `tomllib` and the standard library are enough.
+- Read, write, or log `.env`, `.env.*`, `secrets/**`, or credential files.
+- Edit generated files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/project.mdc`); edit `PROJECT.md` and run `tazuna render`.
+- Add flags to provider definitions that disable a harness's approvals or sandbox (`--dangerously-*`, `--yolo`, `--force`); `run.py` rejects them.
+- Let tests reach a real provider CLI; use the shims in `tests/conftest.py`.
+
+## Known pitfalls
+
+- `is_generated` looks at the first eight lines; a target whose frontmatter is longer will be treated as hand-written. Keep `frontmatter` short.
+- Exit codes are the automation contract. The provider's self-report refines `status` only; never let it change the exit code.
+- Provider CLIs change flags between releases. Verify with `tazuna run --role X --dry-run` after upgrading a CLI, and keep `experimental = true` on definitions nobody has run end to end.
+
+## References
+
+- Architecture: `docs/architecture.md` · Security model: `docs/security.md` · Result contract: `docs/handoff.md`