zeroth-core 0.1.0__tar.gz

zeroth_core-0.1.0/.agents/skills/progress-logger/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: progress-logger
+description: >
+  MANDATORY skill that enforces progress logging on every implementation
+  iteration. Use this skill whenever you are implementing, modifying, fixing,
+  or completing ANY task that maps to a phase in the Zeroth project. This skill
+  must fire BEFORE you report completion and AFTER every meaningful unit of work.
+  Trigger on: finishing a task, completing a checklist item, passing or failing
+  tests, creating or modifying deliverables, hitting a blocker, or changing
+  approach. If you are doing implementation work in this project, this skill
+  applies — no exceptions.
+disable-model-invocation: false
+user-invocable: true
+allowed-tools: Bash, Read, Glob, Grep, Edit, Write
+argument-hint: "[phase/task completed or status update]"
+---
+
+# Progress Logger
+
+Every implementation iteration must update `PROGRESS.md` (root) and, when
+applicable, produce artifacts in the relevant phase's `artifacts/` directory.
+
+## File Layout
+
+```
+PROGRESS.md                          ← single source of truth for all progress + log
+phases/phase-1-foundation/PLAN.md    ← detailed requirements (read only when working on Phase 1)
+phases/phase-1-foundation/artifacts/ ← test output, evidence
+phases/phase-2-execution/PLAN.md
+phases/phase-2-execution/artifacts/
+phases/phase-3-control/PLAN.md
+phases/phase-3-control/artifacts/
+phases/phase-4-deployment/PLAN.md
+phases/phase-4-deployment/artifacts/
+phases/phase-5-integration/PLAN.md
+phases/phase-5-integration/artifacts/
+```
+
+An agent assigned to task "2E" only needs to read:
+1. The 2E section of `PROGRESS.md` (to see current state)
+2. `phases/phase-2-execution/PLAN.md` (for detailed requirements)
+
+Do NOT read `PLAN.md` (root) — it is the master spec, not an implementation guide.
+
+## The Protocol
+
+### Step 1 — Read Current State
+
+Read the relevant section of `PROGRESS.md` to see what's done, in-progress, or blocked.
+If you need detailed requirements, read the phase's `PLAN.md`.
+
+### Step 2 — Update Checkboxes in PROGRESS.md
+
+Edit `PROGRESS.md`:
+
+1. **Completed** — change `[ ]` to `[x]` for tasks you finished
+2. **In-progress** — change `[ ]` to `[~]` for tasks you started but haven't finished
+3. **Blocked** — change `[ ]` to `[-]` and add a note explaining the blocker
+4. **Artifacts** — only mark `**Artifact:**` lines `[x]` when evidence exists
+
+Rules:
+- Never mark `[x]` unless the code exists AND compiles/runs
+- Never mark an artifact `[x]` unless the file is in `artifacts/` or tests pass
+- If you deviated from the plan, add a `> **Note:**` line under the task
+- Update after each completed item, not in batches
+
+### Step 3 — Append to the Log
+
+Append an entry to the `## Log` section at the bottom of `PROGRESS.md`:
+
+```markdown
+### YYYY-MM-DD HH:MM — [brief title]
+**Phase/Tasks:** 1A, 2E, etc.
+**Status:** completed | in-progress | blocked
+**What:** [concrete changes — files created/modified, functions implemented]
+**Tests:** [pass/fail/not run]
+**Artifacts:** [files added to phases/phase-N-*/artifacts/]
+**Blockers:** [none or description]
+**Next:** [what should happen next]
+```
+
+### Step 4 — Produce Artifacts (when applicable)
+
+When an `**Artifact:**` line requires evidence:
+
+- **Test results:** `phases/phase-N-*/artifacts/test-{task}-{date}.txt`
+- **Validation reports:** `phases/phase-N-*/artifacts/validation-{desc}.json`
+- **Build evidence:** `phases/phase-N-*/artifacts/build-{desc}.txt`
+
+Capture output even on failure — failed artifacts are valid evidence.
+
+## Anti-Patterns
+
+| Bad | Good |
+|-----|------|
+| Mark done without code existing | Only mark done when code is saved and works |
+| Skip artifact production | Capture test output when artifact checklist requires it |
+| Vague log ("worked on models") | Specific log ("defined Graph model in src/models/graph.py, 11 fields, serialization test passes") |
+| Batch updates at end of session | Update after each completed item |
+| Mark artifact done without file | Artifact checkbox = file exists in artifacts/ |
+| Read root PLAN.md to start working | Read only the phase PLAN.md you need |
+| Read all PROGRESS.md sections | Read only the section for your task |
+
+## Example
+
+After implementing the Graph model and passing serialization tests:
+
+1. Read 1A section of `PROGRESS.md`
+2. Mark "Define canonical Graph model" as `[x]`
+3. Mark "Artifact: serialization round-trip tests pass" as `[x]`
+4. Save test output to `phases/phase-1-foundation/artifacts/test-1a-graph-serialization-2026-03-18.txt`
+5. Append log entry with what was done, test results, next steps

zeroth_core-0.1.0/.claude/launch.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "studio-mockups",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["--prefix", "apps/studio-mockups", "run", "dev"],
+      "port": 5173
+    },
+    {
+      "name": "zeroth-api",
+      "runtimeExecutable": "uv",
+      "runtimeArgs": ["run", "uvicorn", "zeroth.service.app:app", "--reload", "--port", "8000"],
+      "port": 8000
+    }
+  ]
+}

zeroth_core-0.1.0/.claude/settings.local.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv pip:*)",
+      "Bash(uv run:*)",
+      "Bash(tee .planning/phases/27-ship-zeroth-as-pip-installable-library-zeroth-core/artifacts/interrogate-after.txt)",
+      "Bash(git add:*)",
+      "Bash(git commit --no-verify -m ':*)",
+      "Bash(git push:*)",
+      "Bash(gh repo:*)",
+      "Bash(uv build:*)",
+      "Bash(gh run:*)",
+      "Read(//Users/dondoe/coding/regulus/sdk/python/**)",
+      "Bash(rm -rf dist/)",
+      "Read(//Users/dondoe/coding/governai/**)",
+      "Read(//Users/dondoe/coding/governai/.claude/worktrees/agent-a67b37fb/.github/workflows/**)",
+      "Bash(docker info:*)",
+      "Bash(grep:*)"
+    ]
+  }
+}

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

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run repo checks
+        run: |
+          uv sync --all-groups
+          uv run ruff check src tests
+          uv run pytest -v --no-header -ra
+          uv run interrogate src/zeroth/core

zeroth_core-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+node_modules/
+
+# Local git worktrees
+.worktrees/
+
+# Local brainstorming/visual companion state
+.superpowers/
+
+# Generated local state for live scenarios
+live_scenarios/*.sqlite3
+zeroth.db
+zeroth.db-shm
+zeroth.db-wal
+zeroth_dev.db
+zeroth_dev.db-shm
+zeroth_dev.db-wal
+zeroth_live.db
+zeroth_live.db-shm
+zeroth_live.db-wal

zeroth_core-0.1.0/.planning/MILESTONES.md

@@ -0,0 +1,23 @@
+# Milestones
+
+## v1.1 Production Readiness (Shipped: 2026-04-09)
+
+**Phases:** 11 (Phases 11-21) | **Plans:** 30 | **Timeline:** 4 days
+**Stats:** 168 commits, 350 files changed, +47,444 / -3,273 lines
+
+**Key accomplishments:**
+
+- Real LLM provider integration via LiteLLM routing to 100+ models with exponential backoff retry and token usage audit
+- Regulus economics: per-call cost events, per-tenant budget enforcement with fail-open, cost REST endpoints
+- 8 memory connector types (Redis KV/thread, pgvector, ChromaDB, Elasticsearch, 3 in-memory) bridged to GovernAI v0.3.0 protocol
+- Docker sandbox sidecar architecture with per-execution network isolation
+- Durable webhooks with HMAC signing, dead-letter store, and approval SLA escalation policies
+- Production deployment: multi-stage Dockerfile, 6-service docker-compose, Nginx TLS termination, health probes
+- Native LLM API parity: tool schemas, structured output, model parameters, MCP server connections
+- Postgres storage backend with Alembic migrations, ARQ wakeup, horizontal worker scaling via SKIP LOCKED
+
+**Tech debt at completion:** 8 cosmetic items (stale comments, dead code, duplicate fields, documentation staleness) — 0 blockers
+
+**Archive:** `milestones/v1.1-ROADMAP.md`, `milestones/v1.1-REQUIREMENTS.md`, `milestones/v1.1-MILESTONE-AUDIT.md`, `milestones/v1.1-phases/`
+
+---

zeroth_core-0.1.0/.planning/PROJECT.md

@@ -0,0 +1,132 @@
+# Zeroth
+
+## What This Is
+
+Zeroth is a governed medium-code platform for building, running, and deploying production-grade multi-agent systems as standalone API services. The platform provides graph-based orchestration, typed contracts, sandboxed execution, human approvals, per-node audit trails, identity/RBAC, tenant isolation, deployment provenance, durable dispatch, real LLM provider integration (100+ models via LiteLLM), token economics via Regulus, external memory backends, and containerized deployment with health probes.
+
+## Core Value
+
+Teams can author and operate governed multi-agent workflows without sacrificing production controls, auditability, or deployment rigor.
+
+## Current Milestone: v3.0 Core Library Extraction, Studio Split & Documentation
+
+**Goal:** Ship Zeroth as a pip-installable Python library (`zeroth-core`) with in-depth usage documentation covering every major subsystem, while moving the Vue Studio UI into a separate repo so the two evolve independently.
+
+**Target features:**
+- `zeroth-core` PyPI distribution containing the full Python codebase under `zeroth.core.*` namespace (full rename, zero deletions, all functionality preserved)
+- `econ-instrumentation-sdk` published to PyPI to replace the local file-path dependency
+- `zeroth-studio` separate public repo containing the Vue 3 + Vue Flow frontend, depending on `zeroth-core` via HTTP API only — v2.0 phases 24-26 continue there
+- Complete, in-depth documentation for every `zeroth-core` subsystem: getting started, core concepts, per-module guides (graph, orchestrator, agents, execution units, memory, contracts, runs, conditions, mappings, policy, approvals, audit, secrets, identity, guardrails, dispatch, economics, storage, service), HTTP & Python API references, integration recipes, deployment guide, migration guide
+- Full multi-layer archive of the existing monolithic repo (tarball + bare mirror + GitHub archive)
+
+**Pivot context:** v2.0 Zeroth Studio phases 22-23 are shipped; phases 24-26 (Execution & AI Authoring, Governance Visualization, Versioning & Collaboration) are **not cancelled** — they move to the new `zeroth-studio` repo with their own roadmap. This milestone is a packaging and structural change, not a scope reduction. Most of Phase 0 (preservation) and significant progress on Phase 1 (core library extraction) have been completed ad-hoc prior to formalizing this milestone.
+
+## Prior Milestone: v2.0 Zeroth Studio (partially shipped)
+
+**Status:** Phases 22-23 shipped (2026-04-09). Phases 24-26 deferred to `zeroth-studio` separate repo as part of v3.0 milestone pivot.
+
+**Goal:** Build a visual workflow authoring UI for governed multi-agent systems, using Vue 3 + Vue Flow, informed by n8n's canvas patterns but reimplemented for Zeroth's governance-first domain model.
+
+## Current State
+
+**Shipped:** v1.1 Production Readiness (2026-04-09)
+**Codebase:** ~22K LOC source + ~18K LOC tests (Python)
+**Tech stack:** Python / FastAPI / Pydantic / SQLAlchemy / Alembic / LiteLLM / ARQ / Docker
+**Frontend stack (v2.0):** Vue 3 / Vite / Pinia / Vue Flow / dagre / CodeMirror 6
+
+The platform is production-viable: real LLM providers, economic controls, external memory, durable webhooks, horizontal scaling, and containerized deployment are all wired and verified. v2.0 adds Studio UI for visual workflow authoring. Phase 22 complete — Studio foundation in place with interactive canvas, graph authoring API, and Docker deployment.
+
+## Requirements
+
+### Validated
+
+- ✓ Governed workflow graph modeling, validation, and versioning — v1.0
+- ✓ Runtime orchestration, approvals, memory, and deployment-bound service APIs — v1.0
+- ✓ Identity, governance evidence, runtime hardening, and durable control-plane foundations — v1.0
+- ✓ Unified pydantic-settings config and async Postgres storage backend — v1.1
+- ✓ Real LLM provider adapters (OpenAI, Anthropic via LiteLLM) with retry and token audit — v1.1
+- ✓ Regulus economics: cost events, cost attribution, budget enforcement, cost REST endpoints — v1.1
+- ✓ External memory connectors (Redis KV/thread, pgvector, ChromaDB, Elasticsearch) with GovernAI protocol — v1.1
+- ✓ Container sandbox sidecar architecture — v1.1
+- ✓ Durable webhooks with HMAC signing, retry, dead-letter store — v1.1
+- ✓ Approval SLA timeouts with escalation policies — v1.1
+- ✓ Distributed dispatch with ARQ wakeup and horizontal worker scaling — v1.1
+- ✓ Containerized deployment (Dockerfile, docker-compose, Nginx TLS, health probes) — v1.1
+- ✓ API versioning (/v1/), OpenAPI spec, TLS/HTTPS support — v1.1
+- ✓ Native LLM API parity: tool schemas, structured output, model params, MCP servers — v1.1
+
+### Active (v3.0)
+
+- [ ] Extract all Python code into `zeroth-core` PyPI-installable library under `zeroth.core.*` namespace
+- [ ] Publish `econ-instrumentation-sdk` (Regulus SDK) to PyPI
+- [ ] Move Vue Studio frontend to separate public `zeroth-studio` repo with independent CI
+- [ ] Write in-depth documentation for every `zeroth-core` subsystem (getting started, core concepts, subsystem guides, API references, integration recipes, deployment, migration)
+- [ ] Multi-layer archive of monolithic repo (tarball, bare mirror, GitHub `rrrozhd/zeroth-archive`)
+
+### Deferred to `zeroth-studio` repo (v2.0 phases 24-26)
+
+- [ ] Canvas execution & AI authoring (WebSocket real-time updates, per-node results, model selector, prompt editor, tool attachment)
+- [ ] Governance visualization (approval gates, audit trail, sandbox badges, RBAC-aware canvas, cost/budget display)
+- [ ] Graph versioning & collaborative presence indicators
+
+### Out of Scope
+
+- Mobile apps — web-based platform only
+- Judge/evaluation subsystem — preserved as extension point per original PLAN.md
+- Runtime architecture rewrite — production backend is solid, next work is Studio UI
+- Real-time streaming — async invocation model sufficient
+- Custom LLM hosting — integrates with hosted providers only
+- LLM response caching / model routing optimization — deferred to future economics milestone
+- Model fallback chains / streaming responses — deferred to future provider milestone
+
+## Context
+
+Mature Python backend with 280+ tests, lint clean, broad pytest coverage. GovernAI v0.3.0-dev pinned from GitHub for memory, secrets, capability policy, agent spec, and tool manifest modules. Regulus companion service provides LLM economics telemetry. All v1.1 requirements verified via milestone audit with zero gaps.
+
+**v2.0 design reference:** n8n's frontend (SUL-licensed, not forkable) studied for canvas patterns, shell layout, and inspector UX. MIT libraries adopted directly: @vue-flow/core, @dagrejs/dagre, CodeMirror 6. Our canvas must be governance-aware (approval gates, audit decorators, sandbox indicators, RBAC) — a clean reimplementation, not a port.
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| GovernAI pinned to GitHub commit, not PyPI | v0.3.0 unreleased but has needed memory/secrets/policy modules | ✓ Good |
+| Regulus integrated via SDK, not embedded | Separation of concerns — economics is a companion service | ✓ Good — fail-open pattern works well |
+| Postgres as production storage, SQLite retained for dev/test | Production needs vs developer experience | ✓ Good — dual backend via env var |
+| Studio UI deferred to v2.0 | Backend must be production-viable before adding frontend | ✓ Good — v1.1 shipped solid |
+| Vue 3 + Vue Flow for Studio | Same stack as n8n reference; Vue Flow is purpose-built for Vue, MIT-licensed | — Pending |
+| n8n as design reference only | SUL license prevents forking; tight coupling to n8n backend makes extraction impractical | ✓ Good |
+| LiteLLM as provider abstraction layer | Routes to 100+ models without per-provider adapters | ✓ Good — unified retry/token capture |
+| Worktree isolation for parallel phase development | Independent progress on subsystems | ⚠️ Revisit — creates integration wiring gaps |
+| Bootstrap wiring as dedicated integration phase | Connects independently developed subsystems | ✓ Good — effective gap closure pattern |
+| v3.0 pivot: extract core as pip-installable library before completing Studio | User needs backend library for embedding in their own apps/services; current structure couples UI and backend in one repo | — Pending |
+| Take EVERYTHING into `zeroth.core.*` (no core/platform file split) | Pragmatic: a pure rename avoids refactoring cascade from broken `__init__.py` re-exports; some core functionality requires optional deps to actually use, which is fine | — Pending |
+| PEP 420 namespace `zeroth.core.*` (no top-level `zeroth/__init__.py`) | Leaves room for future sibling packages to share the `zeroth.*` namespace without import collisions | — Pending |
+| Studio UI moves to separate public repo rather than staying in a monorepo | Independent release cadence, simpler CI, clearer separation of backend library vs frontend app | — Pending |
+
+## Constraints
+
+- **Tech stack**: Python/FastAPI/Pydantic backend — all new work integrates with existing foundation
+- **GovernAI**: Pinned to git+https://github.com/rrrozhd/governai.git@7452de4 — use new v0.3.0 modules where applicable
+- **Regulus**: SDK-level integration preferred — Regulus backend runs as companion service, not embedded
+- **Backward compatibility**: Existing tests must continue passing through all changes
+- **Architecture**: Modular monolith — new capabilities are new modules, not separate services (except Regulus backend)
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd:transition`):
+1. Requirements invalidated? Move to Out of Scope with reason
+2. Requirements validated? Move to Validated with phase reference
+3. New requirements emerged? Add to Active
+4. Decisions to log? Add to Key Decisions
+5. "What This Is" still accurate? Update if drifted
+
+**After each milestone** (via `/gsd:complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+
+---
+*Last updated: 2026-04-10 — Milestone v3.0 initialized; pivoting to core library extraction and Studio repo split.*

zeroth_core-0.1.0/.planning/REQUIREMENTS.md

@@ -0,0 +1,180 @@
+# Requirements: Zeroth
+
+**Defined:** 2026-04-09 (v2.0) · **Updated:** 2026-04-10 (v3.0 milestone)
+**Core Value:** Teams can author and operate governed multi-agent workflows without sacrificing production controls, auditability, or deployment rigor.
+
+## v3.0 Requirements — Core Library Extraction, Studio Split & Documentation
+
+v3.0 is a packaging and documentation milestone. No new runtime features. Deliverables: ship `zeroth-core` on PyPI under the `zeroth.core.*` namespace, move the Vue Studio to its own public repo, write in-depth documentation for every subsystem, and formalize the monolith archive.
+
+### Packaging (PKG)
+
+- [ ] **PKG-01**: `econ-instrumentation-sdk` (Regulus SDK) is published to PyPI with a stable version, replacing the current local file-path dependency
+- [ ] **PKG-02**: `zeroth-core` is published to PyPI as a pip-installable library and `pip install zeroth-core` succeeds in a clean virtualenv
+- [ ] **PKG-03**: `pyproject.toml` declares optional-dependency extras for every swappable backend (`[memory-pg]`, `[memory-chroma]`, `[memory-es]`, `[dispatch]`, `[sandbox]`, `[all]`), with each extra verified installable and documented
+- [ ] **PKG-04**: Repository root contains `CHANGELOG.md` (keepachangelog format), `LICENSE`, and `CONTRIBUTING.md` suitable for a public PyPI release
+- [ ] **PKG-05**: PyPI releases are published via GitHub Actions using trusted publisher (OIDC), not a long-lived API token
+- [ ] **PKG-06**: Installing `zeroth-core` from a clean environment and running the Getting Started hello example works end-to-end (acceptance test for the whole packaging stack)
+
+### Namespace Rename (RENAME)
+
+- [ ] **RENAME-01**: All Python source is relocated from `zeroth.*` to `zeroth.core.*` with zero deletions and zero functional changes (pure rename)
+- [ ] **RENAME-02**: The package is a PEP 420 namespace package — no top-level `zeroth/__init__.py` — so future sibling packages (`zeroth.studio`, `zeroth.ext.*`) can coexist under `zeroth.*`
+- [ ] **RENAME-03**: All internal imports, string references, entry points, and console scripts point at the new `zeroth.core.*` paths
+- [ ] **RENAME-04**: The existing test suite (280+ tests) passes against the renamed package with no skips or regressions
+- [ ] **RENAME-05**: Docstring coverage on the public surface of `zeroth.core.*` reaches ≥90% (measured by `interrogate`) with a consistent style (Google-style)
+
+### Documentation Content (DOCS)
+
+- [ ] **DOCS-01**: Landing page presents a 10-line hello-world, install snippet, and a "Choose your path" split between embedding as a library and running as a governed service
+- [ ] **DOCS-02**: Getting Started is a single linear 3-section tutorial (install → first graph with one agent/tool/LLM → run in service mode with an approval gate), reaching first working output in under 5 minutes and completing in under 30
+- [ ] **DOCS-03**: Every major `zeroth.core.*` subsystem has a Concept page (what it is, why it exists, mental model, where it fits) — covering graph, orchestrator, agents, execution units, memory, contracts, runs, conditions, mappings, policy, approvals, audit, secrets, identity, guardrails, dispatch, economics, storage, service, threads
+- [ ] **DOCS-04**: Every major subsystem has a Usage Guide (Overview → Minimal example → Common patterns → Pitfalls → Reference cross-link) paired with its Concept page
+- [ ] **DOCS-05**: A Governance Walkthrough tutorial shows an end-to-end run where an approval gate stops execution, an auditor reviews the trail, and a policy blocks a tool call (Zeroth's differentiator vs. LangGraph/CrewAI)
+- [ ] **DOCS-06**: A Cookbook section contains at least 10 cross-subsystem recipes at launch (examples: add a human approval step, attach pgvector memory to a node, cap a run's budget with Regulus, sandbox a Python execution unit, retry a failed webhook from the DLQ)
+- [ ] **DOCS-07**: Python API Reference is auto-generated from docstrings via mkdocstrings + Griffe for the full public surface
+- [ ] **DOCS-08**: HTTP API Reference is rendered from the FastAPI OpenAPI spec and published alongside the Python reference
+- [ ] **DOCS-09**: Configuration Reference is auto-generated from pydantic-settings schemas and documents every env var, default, and secret
+- [ ] **DOCS-10**: Deployment Guide covers local dev, docker-compose, standalone service mode, embedded-in-host-app mode, and deployments with/without the Regulus companion service
+- [ ] **DOCS-11**: Migration Guide explains how to move from the monolithic `zeroth.*` layout to `zeroth.core.*` (import rename pattern, econ SDK path swap, env var changes, Docker image retag)
+- [ ] **DOCS-12**: An `examples/` directory at the repo root contains runnable `.py` files (not notebooks) exercising the main subsystems, and CI smoke-tests each on every main commit
+
+### Documentation Site Infrastructure (SITE)
+
+- [ ] **SITE-01**: Documentation is built with mkdocs-material using explicit Diátaxis IA (Tutorials / How-to Guides / Concepts / Reference as four top-level sections)
+- [ ] **SITE-02**: A GitHub Actions workflow builds and deploys the docs site to a public URL on every commit to `main`
+- [ ] **SITE-03**: Pull request previews deploy a rendered version of the changed docs so reviewers see the output before merge
+- [ ] **SITE-04**: The docs site includes built-in search and an automatically generated site map
+
+### Studio Repo Split (STUDIO)
+
+- [ ] **STUDIO-01**: A new public repository `rrrozhd/zeroth-studio` contains the Vue 3 + Vue Flow frontend with its full git history preserved (subtree or filter-repo)
+- [ ] **STUDIO-02**: `zeroth-studio` has its own independent CI pipeline (lint, typecheck, build, test) passing on its default branch
+- [ ] **STUDIO-03**: `zeroth-studio` consumes `zeroth-core` only via HTTP/OpenAPI — no Python imports, no shared source tree
+- [ ] **STUDIO-04**: Both repositories' READMEs cross-link to each other, and a cross-repo compatibility matrix (`zeroth-studio` version ↔ `zeroth-core` version) is documented and maintained in at least one of them
+- [ ] **STUDIO-05**: The frontend types used by `zeroth-studio` are generated from the `zeroth-core` OpenAPI spec via `openapi-typescript`, keeping the two in sync without manual edits
+
+### Monolith Archive (ARCHIVE)
+
+- [ ] **ARCHIVE-01**: A multi-layer archive of the pre-split monolithic repo exists and is documented: local tarball, local bare mirror, and GitHub repository `rrrozhd/zeroth-archive`
+- [ ] **ARCHIVE-02**: All 36 worktree branches, both stashes, and the detached-HEAD worktree from the ad-hoc split work are preserved in the archive and recoverable
+- [ ] **ARCHIVE-03**: The archive repository carries a visible "this repo is archived — see rrrozhd/zeroth-core and rrrozhd/zeroth-studio" notice in its README and repo description
+
+## Deferred to v0.2.x of `zeroth-core`
+
+Tracked but out of scope for v3.0 milestone completion. Will be opened as new phases once a first external user has validated the core library.
+
+- [ ] **FUTURE-01**: LibCST codemod (`python -m zeroth.core.codemods.rename_from_monolith`) that automatically rewrites `zeroth.*` imports to `zeroth.core.*` in consumer codebases
+- [ ] **FUTURE-02**: HTTP/curl tabs added inline to every subsystem usage guide (initially Python-only)
+- [ ] **FUTURE-03**: Extension-point guides — "Writing a custom memory connector", "Writing a custom LLM provider", "Writing a custom execution unit", "Writing a custom judge"
+- [ ] **FUTURE-04**: Docstring coverage badge in README
+- [ ] **FUTURE-05**: Governance case studies (real-world workflows with captured audit trails)
+- [ ] **FUTURE-06**: Algolia DocSearch (if docs traffic warrants it)
+
+## Deferred to `zeroth-studio` repo (v2.0 phases 24-26)
+
+These requirements are **not cancelled** — they continue in the new `zeroth-studio` repo after the split and will be roadmapped there separately.
+
+- [ ] **API-02** (from v2.0): Studio receives real-time updates via WebSocket (execution status, validation, presence)
+- [ ] **API-04** (from v2.0): Studio can trigger workflow execution and receive per-node status updates
+- [ ] **AUTH-01** through **AUTH-05** (from v2.0): Canvas execution & AI authoring (model selector, prompt editor, tool attachment, data-flow tooltips, per-node results)
+- [ ] **GOV-01** through **GOV-07** (from v2.0): Governance visualization (approval gates, audit trails, sandbox badges, RBAC-aware canvas, cost/budget display, env switching)
+- [ ] **COLLAB-01**, **COLLAB-02** (from v2.0): Graph version diff view, collaborative presence indicators
+
+## Out of Scope
+
+Explicitly excluded for v3.0. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| Multi-version docs site with version dropdown (`mike` plugin) | Pre-1.0 — API still shifts, stale versions confuse more than help. Revisit at 1.0. |
+| Translations / multi-language docs | FastAPI has 12 language maintainers; we have one team. Translations rot faster than code. |
+| Hand-written API reference for every class | 22K LOC — impractical and goes stale on day one. Use mkdocstrings instead. |
+| Jupyter notebook examples | Hard to version-control, diff, and CI-test. Use plain `.py` files. |
+| Video tutorials / screencasts | Expensive to produce, impossible to update in place, SEO/search unfriendly. |
+| Public Discord/Slack community at launch | Pre-1.0 support burden. GitHub Issues + Discussions only. |
+| "Awesome Zeroth" curated extension list | No ecosystem exists yet — would look abandoned. |
+| Core/platform file-level split | Superseded by the pure-rename decision — the cascading `__init__.py` breakage isn't worth it. |
+| Monorepo consolidation of `zeroth-core` + `zeroth-studio` | Directly contradicts the intentional split decision. |
+| Runtime feature work (new subsystems, new integrations) | v3.0 is packaging and docs only. New runtime work goes to v3.1+. |
+
+## Traceability
+
+Which phases cover which requirements. Updated after roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| PKG-01 | Phase 28 | Pending |
+| PKG-02 | Phase 28 | Pending |
+| PKG-03 | Phase 28 | Pending |
+| PKG-04 | Phase 28 | Pending |
+| PKG-05 | Phase 28 | Pending |
+| PKG-06 | Phase 28 | Pending |
+| RENAME-01 | Phase 27 | Pending |
+| RENAME-02 | Phase 27 | Pending |
+| RENAME-03 | Phase 27 | Pending |
+| RENAME-04 | Phase 27 | Pending |
+| RENAME-05 | Phase 27 | Pending |
+| DOCS-01 | Phase 30 | Pending |
+| DOCS-02 | Phase 30 | Pending |
+| DOCS-03 | Phase 31 | Pending |
+| DOCS-04 | Phase 31 | Pending |
+| DOCS-05 | Phase 30 | Pending |
+| DOCS-06 | Phase 31 | Pending |
+| DOCS-07 | Phase 32 | Pending |
+| DOCS-08 | Phase 32 | Pending |
+| DOCS-09 | Phase 32 | Pending |
+| DOCS-10 | Phase 32 | Pending |
+| DOCS-11 | Phase 32 | Pending |
+| DOCS-12 | Phase 31 | Pending |
+| SITE-01 | Phase 30 | Pending |
+| SITE-02 | Phase 30 | Pending |
+| SITE-03 | Phase 30 | Pending |
+| SITE-04 | Phase 30 | Pending |
+| STUDIO-01 | Phase 29 | Pending |
+| STUDIO-02 | Phase 29 | Pending |
+| STUDIO-03 | Phase 29 | Pending |
+| STUDIO-04 | Phase 29 | Pending |
+| STUDIO-05 | Phase 29 | Pending |
+| ARCHIVE-01 | Phase 27 | Pending |
+| ARCHIVE-02 | Phase 27 | Pending |
+| ARCHIVE-03 | Phase 27 | Pending |
+
+**Coverage:**
+- v3.0 requirements: 34 total
+- Mapped to phases: 34
+- Unmapped: 0
+
+---
+
+## v2.0 Requirements (Zeroth Studio — partially shipped)
+
+Phases 22–23 shipped in v2.0. Phases 24–26 deferred to the new `zeroth-studio` repo — see "Deferred to `zeroth-studio` repo" above. v2.0 REQ-IDs are preserved for history but not re-mapped in v3.0.
+
+### Canvas Foundation
+
+- [x] **CANV-01** · [x] **CANV-02** · [x] **CANV-03** · [x] **CANV-04** · [x] **CANV-05** · [x] **CANV-06** · [x] **CANV-07** · [x] **CANV-08** · [x] **CANV-09** · [x] **CANV-10**
+
+### Graph Authoring API
+
+- [x] **API-01** · [x] **API-03** · [ ] **API-02** (→ zeroth-studio) · [ ] **API-04** (→ zeroth-studio)
+
+### Governance Visualization
+
+- [ ] **GOV-01** … **GOV-07** (→ zeroth-studio)
+
+### AI Authoring
+
+- [ ] **AUTH-01** … **AUTH-05** (→ zeroth-studio) · [x] **AUTH-06**
+
+### Versioning & Collaboration
+
+- [ ] **COLLAB-01** · [ ] **COLLAB-02** (→ zeroth-studio)
+
+### Deployment & Infrastructure
+
+- [x] **INFRA-01** · [x] **INFRA-02**
+
+---
+
+*Requirements last updated: 2026-04-10 after v3.0 milestone kickoff.*

zeroth_core-0.1.0/.planning/RETROSPECTIVE.md

@@ -0,0 +1,63 @@
+# Project Retrospective
+
+*A living document updated after each milestone. Lessons feed forward into future planning.*
+
+## Milestone: v1.1 — Production Readiness
+
+**Shipped:** 2026-04-09
+**Phases:** 11 | **Plans:** 30
+
+### What Was Built
+- Real LLM provider integration via LiteLLM with exponential backoff retry and token usage capture
+- Regulus economics: per-call cost events, per-tenant budget enforcement, cost REST endpoints
+- 8 memory connector types (3 in-memory, 2 Redis, 3 vector/search) bridged to GovernAI v0.3.0 protocol
+- Docker sandbox sidecar with per-execution network isolation
+- Durable webhooks with HMAC signing, dead-letter store, and approval SLA escalation
+- Production deployment: multi-stage Dockerfile, 6-service docker-compose, Nginx TLS, health probes
+- Native LLM API parity: tool schemas, structured output, model params, MCP server connections
+- Postgres storage backend with Alembic migrations, ARQ wakeup, horizontal worker scaling
+
+### What Worked
+- Phase-based parallel development with worktree isolation allowed independent progress on 11 phases
+- Gap closure phases (18, 20, 21) effectively caught integration issues post-merge
+- Milestone audit workflow identified real integration gaps (INT-01, INT-02, INT-03) that would have been missed
+- GovernAI protocol alignment kept memory connectors interchangeable across all backends
+
+### What Was Inefficient
+- Some ROADMAP.md plan checkboxes drifted from actual completion status (11-02, 12-01, 13-02 unchecked despite work complete)
+- SUMMARY.md frontmatter `requirements_completed` was inconsistently populated across ~20 requirements
+- Phase 18 marked "In Progress" in ROADMAP despite verification passing — documentation staleness accumulated
+- 3 gap closure phases (18, 20, 21) needed after initial 8 phases — integration wiring should be considered earlier
+
+### Patterns Established
+- Milestone audit (requirement/integration/flow cross-reference) as gate before completion
+- Gap closure phases numbered sequentially after initial phases rather than inserted
+- Tech debt tracked as non-blocking audit items separate from requirement gaps
+- Bootstrap wiring as dedicated phase pattern for connecting independently developed subsystems
+
+### Key Lessons
+1. Worktree-isolated parallel development creates merge/wiring gaps — plan an integration wiring phase from the start
+2. Documentation metadata (checkboxes, frontmatter) needs automated verification, not manual tracking
+3. Audit-driven gap closure is effective but reactive — proactive integration testing between phases would be cheaper
+4. Fail-open patterns (budget enforcement when Regulus is down) are the right default for optional companion services
+
+### Cost Observations
+- 168 commits across 4 days
+- 350 files changed, +47,444 / -3,273 lines
+- Codebase: 21,928 LOC source + 18,035 LOC tests
+
+---
+
+## Cross-Milestone Trends
+
+### Process Evolution
+
+| Milestone | Phases | Plans | Key Change |
+|-----------|--------|-------|------------|
+| v1.0 | 9 | 13 | Foundation: graph, orchestration, governance, deployment |
+| v1.1 | 11 | 30 | Production hardening: real providers, economics, infra, deployment |
+
+### Top Lessons (Verified Across Milestones)
+
+1. Phase-based planning with explicit success criteria prevents scope creep
+2. Integration wiring between independently developed subsystems needs its own phase