deviatdd 2.24.0__tar.gz → 2.24.2__tar.gz

{deviatdd-2.24.0 → deviatdd-2.24.2}/CHANGELOG.md

@@ -43,8 +43,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`deviate html prd --bucket <slug>` targets a specific epic when more than one owns a `prd.md`.** Previously the command hard-failed with `HTML_AMBIGUOUS_PRD` whenever multiple numbered epics had a `prd.md` and offered no flag to disambiguate — the agent was told to "run from within the epic's worktree", which silently yielded `HTML_NO_PRD` because the resolver reads `specs/` from the repo root. The new option resolves `specs/<bucket>/prd.md` directly and bypasses ambiguity detection; the plain form keeps its existing behavior but its ambiguity banner now points at the flag. An unknown/absent bucket exits `PRD_NOT_FOUND`. The `/deviate-html` prompt (`src/deviate/prompts/commands/deviate-html.md`) and spec docs now reference `--bucket` instead of the broken cwd fallback. Pinned by `tests/test_cli/test_html.py::test_html_prd_bucket_targets_specific_epic`, `::test_html_prd_bucket_targets_unnumbered_dir`, and `::test_html_prd_bucket_missing_file_exits_cleanly`.
 - **Optional push-as-lock: `claim_remote` config plus `--local` on `meso run` and `run`.** Standing `.deviate/config.toml` key `claim_remote` plus `--local` on `meso run` and `run`. `deviate setup --no-claim-remote` writes `claim_remote = false` without dropping `[models]`, `timeout_seconds`, or `[agent]`. Effective local mode is `--local` OR `claim_remote = false`; explicit `--local` always wins. Local mode still creates `.worktrees/feat/{epic}/{issue}/`, writes SPECIFIED, and commits the claim, and skips `branch_exists_on_remote` plus `git push`. `deviate specify --local` stays; omitted `--local` honors config. `deviate meso run --local` and `deviate run --local` share that meaning. `--no-setup` remains a distinct skip of worktree plus claim. Local discovery does not treat an origin branch as claimed-elsewhere. Specs: `specs/DeviaTDD-api.md`, `specs/DeviaTDD-architecture.md`. Pinned by `tests/test_state/test_config.py`, `tests/test_cli/test_meso.py`, `tests/test_meso/test_specify.py`, `tests/test_meso/test_meso_orchestration.py`, `tests/test_cli/test_init.py`, and `tests/test_cli/test_top_level_run.py`.
 ### Changed
+- **PRD and shard ownership split for flexible vertical issue slicing (GH-141).** PRD owns behavior, constraints, acceptance criteria, and FR traceability and must not prescribe issue count, issue IDs, or shard topology. Shard owns issue count, grouping, boundaries, and the dependency DAG. Issues are independently testable vertical slices cut by observable behavior first — not partitioned or bounded by FR id. FRs are coverage attached after the slice exists (a set property: every PRD FR must appear in at least one issue; it does not matter which). One issue may cover multiple related FRs; one FR may span multiple issues when each owns a distinct observable behavior. No fixed min/max issue count (hard ten-slice ceiling and `SLICE_CAP_EXCEEDED` removed). Horizontal layer splits remain rejected by default; a persistence-only vertical is valid when the database invariant or migration is the behavior under test. Zero-FR setup/tooling/governance shards stay invalid. Pinned by `tests/test_meso/test_auto_prompt_templates.py::TestPrdShardOwnership`.
+- **Research is one agent / two ordered jobs; explore inventories siblings; PRD selects on the floor/bracket (GH-139).** Auto `research.md` no longer dispatches sequential AlphaBeta/Gamma sub-agents or forwards context between two processes — the same agent writes the floor (constitution + sibling parity + authorization/money safety/provider correctness/data integrity) then attacks it. Schema tables are floor only; named extras live in a Deferred / maximal bracket list and carry Scope Status `Required` | `Recommended` | `Deferred` | `Open Decision`. Explore stays factual and adds a short sibling-flow inventory (amount vs fee, lock vs reserve, vendor call, idempotency, destination shape). PRD in-scope is floor + promoted extras; unused Recommended/Deferred extras stay under Out-of-Scope Boundaries. Auto prompts remain canonical; derived slash commands pick up the gates via `_derive_manual_body`. Specs: `specs/DeviaTDD-architecture.md`, `specs/DeviaTDD-api.md`. Pinned by `tests/test_macro/test_scope_gates.py`.
+- **README first-hour path and `deviate setup --help` match shipped 2.24.0 setup.** Quickstart names the TTY extras `--agent` does not skip (`[l]ocal/[g]lobal`, claim-remote, pack checklist), the Pi local vs `~/.pi/agent/` paths, `/deviate-init` vs `/skill:deviatdd`, and empty `CLAUDE.md` after setup. Phase rationale moved to `docs/rationale.md`. `setup --help` documents those TTY extras, omitted `--packs` off-TTY = default layers, and `--agent-export-mode` as this-run only. Global command install prints the dest path the way the skill path is printed. Help copy is documentation, not a pytest contract.
 - **`deviate setup` no longer asks or writes `base_branch`.** Trunk is resolved at runtime by `resolve_base_branch`: hand-set `config.toml` `base_branch` if present, else `origin/HEAD`, else `main`. `--base-branch` is a script-only write-override. Pinned by `tests/test_state/test_config.py` and `tests/test_cli/test_setup.py::TestSetupConfigAllowlist`.
-- **`deviate setup` TTY asks prompt/skill install `[l]ocal/[g]lobal`; generated `config.toml` is runner config only.** After the agent picker: export mode (default `l`, this run only — not persisted), then claim-remote, then the pack checkbox. Prompt copy uses ``rich.markup.escape`` so ``[y]es/[n]o`` and ``[l]ocal/[g]lobal`` render as literals. `--agent-export-mode` omitted on a TTY prompts (option default is `None`; non-TTY omitted installs local). `--base-branch` is a script-only write-override (omitted = do not write `base_branch`). `global` installs under `~/.{agent}/…` (Codex: `~/.agents/skills`). Fresh dump has inline comments and no `base_branch`, `agent_export_mode`, or `[agent].timeout` (`timeout_seconds` is the only timeout key). TTY/flag re-runs strip leftover `agent_export_mode` / `[agent].timeout` and leave a hand-set `base_branch` alone. Still no `~/.pi/agent/` writes. Pinned by `tests/test_cli/test_setup.py::TestSetupConfigAllowlist` / `::TestSetupExportModeAndBaseBranch` and `tests/test_cli/test_init.py::test_prompt_claim_remote_escapes_rich_brackets`.
+- **`deviate setup` TTY asks prompt/skill install `[l]ocal/[g]lobal`; generated `config.toml` is runner config only.** After the agent picker: export mode (default `l`, this run only — not persisted), then claim-remote, then the pack checkbox. Prompt copy uses ``rich.markup.escape`` so ``[y]es/[n]o`` and ``[l]ocal/[g]lobal`` render as literals. `--agent-export-mode` omitted on a TTY prompts (option default is `None`; non-TTY omitted installs local). `--base-branch` is a script-only write-override (omitted = do not write `base_branch`). `global` installs under `~/.{agent}/…` (Codex: `~/.agents/skills`). Fresh dump has inline comments and no `base_branch`, `agent_export_mode`, or `[agent].timeout` (`timeout_seconds` is the only timeout key). TTY/flag re-runs strip leftover `agent_export_mode` / `[agent].timeout` and leave a hand-set `base_branch` alone. Pi `global` writes `~/.pi/agent/prompts` + `~/.pi/agent/skills` (see Added); setup still does not generate `settings.json`. Pinned by `tests/test_cli/test_setup.py::TestSetupConfigAllowlist` / `::TestSetupExportModeAndBaseBranch` and `tests/test_cli/test_init.py::test_prompt_claim_remote_escapes_rich_brackets`.
 - **`deviate setup` TTY optional-pack picker is a checkbox list (one pack per row).** Space toggles, Enter confirms, default nothing selected (macro+meso+micro only). Replaces the Rich `Prompt.ask` slash-separated list that wrapped mid-name (`pr` / `une`). `--packs` for scripts is unchanged. Non-TTY still default-only. Selection is not persisted in `config.toml`. Arrow keys stay in the list: CSI (`\\x1b[A`/`[B`) and SS3 (`\\x1bOA`/`OB`) are read with VMIN=0 VTIME=1 (no select race); lone ESC is ignored, not confirm. Pending stdin is flushed before the checklist so a leftover Enter from the agent/`claim_remote` `Prompt.ask` cannot auto-confirm empty. On a TTY re-run, the claim-remote `[y]es/[n]o` prompt always appears (default = current `claim_remote` in `config.toml`; accepts `y`/`n`/`yes`/`no`) and the answer is upserted; flags still skip it. Pinned by `tests/test_cli/test_setup.py::TestSetupPacks` (TTY helper invoked; mocked `product`+`pr` installs those two only), `tests/test_ui/test_checkbox.py`, and `tests/test_cli/test_init.py` claim-remote TTY re-run cases.
 - **Gate 3 `/deviate-walkthrough` is a four-look map; `/deviate-review` is the PR review (comments by default, `--apply` CRITICAL-only).** Walkthrough maps THIS issue/PR: (a) brief path + this issue's plan AC lines if `plan.md` exists; (b) test hunks; (c) which production hunks claim which named check; (d) the command to run those checks. It must not reimplement, approve, hide hunks, tell the human to skip a look, or auto-edit. `deviate walkthrough pre` emits `issue_brief_path`, `plan_path` (null if absent), and classified `test_files` / `production_files`; it no longer sends constitution/prd as default inputs unless this brief names those paths. `/deviate-review` is comments-only by default (stdout and/or GitHub PR review event `COMMENT`); no edits, no `git add`/`git commit`, no `REQUEST_CHANGES`, not a merge gate. There is no always-on STEP 4. `deviate review --apply` (or `pre --apply`) may apply CRITICAL findings only (security / data loss / broken build / named-check fail with a concrete FIX) and commit only when such a fix landed; never auto-apply SUGGESTION or OPPORTUNITY. Same inputs → same comments, keyed by named-check tokens + test-weakening + this-issue cross-task drift. A brief with no named checks emits exactly `brief incomplete` (do not hunt Explore). Do not assume JUDGE already ran (`--profile fast` coworker path). `review_coverage.py` uncovered plan-AC tokens stay as comment input; `coverage_complete` is not an apply gate. Both remain optional packs (`walkthrough`, `review`); no `pr-review` pack. Pinned by CLI contracts in `tests/test_cli/test_review.py` and `tests/test_cli/test_walkthrough.py` (JSON fields, `brief incomplete`, default no-apply, `--apply` CRITICAL-only) — not by prompt-body substring tests.
 - **`deviate --help` and the README now say which phases commit, spawn, or fail closed.** A short per-phase transparency table covers setup, adhoc, meso, micro, review, and walkthrough (does / commits / debug a fail): RED `git commit --no-verify`, Codex `codex exec --sandbox workspace-write --ask-for-approval never`, nested spawn inside `meso run` / `micro run`, `pre`/`post`, `--profile fast` skips JUDGE **and** REFACTOR, `deviate micro run --review` is a TTY pause (not `/deviate-review`; skill argument `review` is a loop policy), default packs on current main (#134) vs optional packs, `--no-setup --local` Path A, `claim_remote` default false, `/deviate-review` comments-only (not a merge gate; opt-in `--apply` CRITICAL-only), and `/deviate-walkthrough` as the four-look map. Typer help on `setup`, `meso run`, `micro run` (`--profile` / `--review` / `--all`) names the same contract. Help copy is documentation, not a pytest contract.
@@ -80,6 +83,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`/deviate-merge` no longer auto-pushes after the squash-merge commit; the push gate runs inline and the network push is opt-in.** The slash command previously ran `git push` as its final step. As of v2.4.0 the squash-merge commit lands on `main`, then a new `push_gate` step inlines the body of `.githooks/pre-push` (lint + format-check + testmon-driven affected tests with the warm-cache / full-suite fallback — bash 3.2 portable, `GIT_DIR` reset + trap preserved) so the safety net fires even though no `git push` happens yet. After the gate passes the skill asks the operator whether to `git push` (which fires the real `pre-push` hook and re-runs the same gate) or stop and push manually. The squash-merge commit and the ledger transition inside it are durable on `main` regardless of the push outcome — only the network push is deferred. New failure states: `Push_Gate_Failed` (inline gate non-zero), `Push_Failed` (`git push` non-zero, raw stderr surfaced), `Push_Deferred` (user chose "Stop — I'll push manually"). Inline gate body and `.githooks/pre-push` body must stay byte-equivalent; divergence is pinned by `tests/test_meso/test_auto_prompt_templates.py::TestMergePromptPushGate::test_hook_and_prompt_agree_on_gate_body` (which compares non-blank non-comment lines in both bodies and fails on drift in either direction) plus 3 supporting assertions on the upstream-first logic, the testmon fallback, and the prompt structure. Prompt: `src/deviate/prompts/commands/deviate-merge.md` (v2.3.0 → v2.4.0). Spec mirrors updated: `specs/DeviaTDD-architecture.md` (Merge bullet, new `**Push gate + opt-in push (v2.4.0)**` sub-bullet) and `specs/DeviaTDD-api.md` (new `**/deviate-merge push behavior (v2.4.0)**` entry under the `deviate merge` reference).
 
 ### Fixed
+- **Research and PRD no longer inflate scope or paper over artifact disagreement (GH-139).** `populate_constitution` is gated on greenfield / placeholder TBD seed and must not rewrite a real constitution. PRD halts with `UPSTREAM_INCONSISTENT` when `design.md` and `data-model.md` disagree on a field, state, or storage type, and `SCOPE_DRIFT` when a required item has no approved upstream Required source. Recommended/Deferred mitigations are not promoted into FRs/NFRs/ACs. Authorization/ownership, amount + fee, reserve/consume/release, skip_locked, one vendor create, UNKNOWN vs fail-open, and typed destination snapshot stay Required. Pinned by `tests/test_macro/test_scope_gates.py` and the parallel-withdrawal fixture under `tests/fixtures/scope_gates/`.
+- **Derived manual slash commands no longer duplicate `$ARGUMENTS`.** The six overlapping auto cores (`explore`, `research`, `prd`, `shard`, `plan`, `tasks`) dropped the trailing `<user_input>$ARGUMENTS</user_input>` block. That seam belongs only on the per-phase overlay, so install no longer expands the operator input twice. Pinned by `tests/test_core/test_commands.py::TestManualDerivationFromAutoCore::test_derived_overlapping_phases_have_one_arguments_seam`.
+
 - **Pi spawn no longer passes `--no-extensions` (ISS-ADH-033 fallout, regression from ISS-ADH-026).** Extension-registered providers (such as `pi-commandcode-provider`) must load so pi resolves a saved default model from that provider. With `--no-extensions`, headless `deviate meso/micro` runs silently fell back to the first model the operator's env keys authenticate (observed: `deepseek/deepseek-v4-pro` → HTTP 402 `Insufficient Balance`). Lean tool policy is unchanged: `--tools read,bash,edit,write`, `--no-skills`, optional `--skill`. Specs: `specs/DeviaTDD-api.md` (7), `specs/DeviaTDD-architecture.md` §10. Pinned by `tests/test_core/test_agent.py`, `tests/core/test_agent.py`, and `tests/e2e/test_pi_spawn_lean_tool_schema.bats`.
 - **`deviate setup` on a TTY always picks exactly one agent and lists every optional pack.** Bare `setup` no longer fans out to every leftover `.claude/` / `.opencode/` / … directory via `detect_agents`, and no longer silently uses `detected[0]`. `--agent <name>` pins that one target without prompting (including when leftover dirs exist). On a TTY, omitted `--agent` always shows the Rich agent menu (`AGENT_CHOICES`; existing `[agent].backend` is the default highlight, not an auto-skip). Non-TTY without `--agent` reuses a persisted backend or fail-closes with `NO_AGENT_SELECTED`. The optional-pack prompt is a Rich selector that names every pack (`merge`, `pr`, `review`, `walkthrough`, `html`, `hotfix`, `triage`, `prune`, `e2e`) plus `none` / `all-optional` (default `none`); `--packs` stays for scripts. `_resolve_install_agents` always returns a one-element list. Pinned by `tests/test_cli/test_setup.py::TestSetupPacks` / `::TestSetupPerAgentInstall` and `tests/e2e/test_setup_config_rework.bats`.
 - **`deviate setup --agent X` now installs slash commands and the packaged `deviatdd` skill only for X.** Previously setup wrote into all five of `.claude/`, `.opencode/`, `.factory/`, `.pi/`, and `.omp/` regardless of `--agent`; the flag only persisted `[agent].backend`. `droid` still writes `.factory/` only. Unknown `--agent` values stay fail-closed. Pinned by `tests/test_cli/test_setup.py::TestSetupSelectedAgentIsolation`.

deviatdd-2.24.2/PKG-INFO

@@ -0,0 +1,353 @@
+Metadata-Version: 2.5
+Name: deviatdd
+Version: 2.24.2
+Summary: DeviaTDD CLI — agent orchestration framework
+Project-URL: Homepage, https://github.com/wernerbisschoff/deviatdd
+Project-URL: Repository, https://github.com/wernerbisschoff/deviatdd
+Project-URL: Issues, https://github.com/wernerbisschoff/deviatdd/issues
+Project-URL: Changelog, https://github.com/wernerbisschoff/deviatdd/blob/main/CHANGELOG.md
+Author: Werner Bisschoff
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-orchestration,ai-coding-agents,spec-driven-development,tdd,test-driven-development
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-testmon>=2.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+<img src="deviatdd.png" alt="DeviaTDD logo" width="435"/>
+</p>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![uv](https://img.shields.io/badge/managed%20with-uv-purple.svg)](https://docs.astral.sh/uv/)
+[![PyPI](https://img.shields.io/pypi/v/deviatdd)](https://pypi.org/project/deviatdd/)
+
+# DeviaTDD
+
+> **An agent-orchestration framework that runs your entire TDD loop — explore, spec, red, green, refactor — with two hard human-in-the-loop gates (design/contract review and merge review); shard is a soft review.**
+
+DeviaTDD is a CLI that coordinates AI coding agents across the full Test-Driven Development lifecycle, from problem framing through documentation. It ships with a four-layer architecture (Product · Macro · Meso · Micro), append-only ledgers, worktree isolation, and path-scoped GREEN writes. The system is **agent-agnostic** — Claude Code, OpenCode, Pi, Droid, the Factory Droid IDE, and Oh-My-Pi are first-class backends today.
+
+---
+
+## Why DeviaTDD?
+
+Most AI coding agents stop at "write code that passes." DeviaTDD goes further — it runs the entire engineering loop with verification, not just generation:
+
+| Without DeviaTDD | With DeviaTDD |
+|------------------|---------------|
+| Agent writes code, you review after | Two hard human gates (design/contract review, merge); shard is a soft review |
+| Test edits slip in silently during "GREEN" | JUDGE flags out-of-scope writes to `tests/`, `specs/`, or protected modules as `COMPLIANCE_VIOLATION` |
+| Lost track of which task is in which state | Append-only JSONL ledgers derive canonical state |
+| Branch drift between parallel features | Worktree isolation + append-only ledger merge driver |
+| Locked to one agent vendor | First-class support for Claude, OpenCode, Pi, Droid, Factory, and OMP |
+| Specs drift from implementation | Spec-enriched issue files with FR traceability |
+
+---
+
+## Quickstart
+
+```bash
+# Install (requires Python 3.13+ and uv).
+# The PyPI package is `deviatdd`; the CLI binary it installs is `deviate`.
+
+uv tool install deviatdd
+deviate --version
+
+# Writes .deviate/, persists the agent, installs default packs
+# (including deviate-init) and the shared deviatdd skill.
+# Does not write specs/constitution.md, mise.toml, or specs/issues.jsonl.
+deviate setup --agent pi     # or: claude | opencode | droid | factory | omp | codex
+```
+
+`--agent` skips **only** the agent picker. A TTY still asks `[l]ocal/[g]lobal`, then claim-remote `[y]es/[n]o` (default `n`), then a pack checklist (Enter = none). Skip those with `--agent-export-mode local|global --packs none --no-claim-remote`.
+
+### Where files go (Pi)
+
+| Mode | Prompt templates | Skill |
+|------|------------------|-------|
+| **local** | `<repo>/.pi/prompts` | `<repo>/.pi/skills/deviatdd` |
+| **global** | `~/.pi/agent/prompts` | `~/.pi/agent/skills/deviatdd` |
+
+Global still writes **cwd** `.deviate/`. Other agents: local is `<repo>/.<agent>/…`; global is `~/.<agent>/…` (Codex: `~/.agents/skills`).
+
+### First hour
+
+Open the agent and run **`/deviate-init` as the first prompt**. That scaffolds `specs/constitution.md`, `mise.toml`, and `specs/issues.jsonl`, skipping anything already present.
+
+- **Pi:** `/deviate-init` is a prompt template from `deviate-init.md`, **not** the `deviatdd` skill. The skill is `/skill:deviatdd` (micro loop).
+- **Codex:** the same prompt, installed as the `deviate-init` skill.
+- **No agent:** `deviate init pre && deviate init post` stages constitution / mise / `issues.jsonl`; it does **not** commit.
+
+Empty `CLAUDE.md` / `AGENTS.md` after setup is expected.
+
+Then drive the rest of the lifecycle from inside your agent. Each phase emits a single artifact; **`post` often commits it** (you did not type `git commit`). At the two gates the workflow pauses for human review. See [Phase transparency](#phase-transparency) for which commands commit, spawn, or fail closed.
+
+**Product layer** *(optional, for cross-product framing — skip if your repo only ships single features):*
+
+```
+/deviate-flows         "Onboard a new tenant"      # FLOW-01 customer flow → specs/_product/flows/
+/deviate-architecture                                # FLOW-02 cross-epic architecture → specs/_product/architecture.md
+/deviate-release        "Ship the v2 onboarding"    # FLOW-03 release plan → specs/_product/release-next.md
+```
+
+**Macro** — pick one of two paths. Full path for new features, the `adhoc` shortcut for low/medium-complexity tasks:
+
+```
+# Full path: feature scoping with a Gate 1 design review
+/deviate-explore "Add user authentication via OAuth2"
+/deviate-research                          # ← Gate 1: review design.md + data-model.md
+/deviate-prd
+/deviate-shard                             # ← review every ISS-NNN spec-enriched issue (soft review — system auto-advances to Meso; not a hard HITL gate)
+
+# — or — Adhoc shortcut for low/medium-complexity work
+/deviate-adhoc "Add a /healthz endpoint"   # condenses explore+research+prd+shard into one issue
+```
+
+**Meso — claim the issue and enter its worktree.** Default meso uses a worktree. `claim_remote` defaults **false** (local claim only; no push lock). Path A coworker flow stays in this clone: `deviate meso run --no-setup --local`. Meso slash commands run inside the per-issue worktree; claim first, then `cd` in:
+
+```
+# From the main checkout (NOT inside a worktree):
+deviate specify                            # auto-claim the next unblocked BACKLOG issue, create .worktrees/<branch>/, print the path
+#   or, to claim a specific issue by ID:
+deviate specify ISS-001-007                # claim that exact issue; same worktree creation
+cd $(deviate specify ISS-001-007 2>&1 | grep '^WORKTREE' | awk '{print $2}')
+                                           # then re-open the agent inside the worktree
+
+# Path A (this clone, no worktree, no remote lock):
+deviate meso run --no-setup --local --issue ISS-001-007
+```
+
+**Meso** — with the worktree active, decompose into tasks. `tasks.md` is the human's execution blueprint:
+
+```
+# Now INSIDE the worktree:
+/deviate-plan                              # per-issue localized research → plan.md
+/deviate-tasks                             # → tasks.md: 4-8 tasks, each with Verification CLI
+                                           #   TDD tasks flow to the Red→Green→Judge→Refactor loop;
+                                           #   IMMEDIATE tasks flow to /deviate-execute
+```
+
+**Micro** — for each task, pick the loop that fits:
+
+```
+# TDD cycle (default for TDD-typed tasks)
+/deviate-red      T001                   # write a failing test
+/deviate-green    T001                   # implement it; GREEN is bounded to src/ + permitted paths
+/deviate-judge    T001                   # Gate decision; on rejection, the
+                                         # Green → Judge → Green loop kicks in
+                                         # (revert + <train_feedback> → re-GREEN, up to 3x)
+/deviate-refactor T001                   # only on JUDGE_PASS
+
+# — or — Direct path for low-complexity tasks (boilerplate, config, trivial fixes)
+/deviate-execute  T002                   # skips the TDD cycle; still has its own JUDGE pass
+```
+
+**Release** — close the loop. `/deviate-pr`, `/deviate-review`, and `/deviate-walkthrough` are **optional packs** (not in default setup):
+
+```
+/deviate-pr       T001                   # conventional-commit PR; merge appends COMPLETED
+/deviate-review                          # ← Gate 3: comments-only PR scan (not a merge gate)
+/deviate-walkthrough                     # four-look map (brief, tests, production vs checks, command)
+```
+
+**Or, run the unattended one-shot pipeline** — the top-level
+`deviate run` is the unattended drain that *replaces* the Meso · Claim,
+Meso · Plan, Meso · Tasks, and Micro steps above with a single command.
+It discovers the next BACKLOG issue, claims it (creating the per-issue
+worktree), runs SPECIFY → PLAN → TASKS in the worktree, then drains
+every PENDING task through the TDD cycle. Under the hood it chains
+`deviate meso run` with `deviate micro run --all` inside the created
+worktree. Use it when you trust the agent to run end-to-end; use the
+manual Meso + Micro blocks above when you want to review plan.md and
+tasks.md between phases:
+
+```
+deviate run                              # full pipeline (meso + micro --all)
+deviate run --issue ISS-001-007          # target a specific BACKLOG issue
+deviate run --profile fast               # skip JUDGE + REFACTOR in the micro drain
+deviate run --no-judge --no-refactor     # same, via boolean overrides
+```
+
+For per-task or `deviate micro run --all` invocations inside an
+already-claimed worktree, see [`deviate micro run`](https://github.com/wernerbisschoff/deviatdd):
+top-level `run` does both meso and micro for you; the per-task
+dispatcher is `deviate micro run <task-id>` and the queue drain is
+`deviate micro run --all`.
+
+The full lifecycle takes you from a problem statement to merged, tested code with a documented audit trail.
+---
+
+## Architecture: Four Layers, Two Gates
+
+```mermaid
+flowchart TB
+subgraph Product["Product Layer — Customer & Release Framing (optional)"]
+  F[flows] --> A[architecture]
+  A --> R[release]
+end
+
+subgraph Macro["Macro Layer — Feature Scoping"]
+  E[explore] --> Re[research]
+  Re --> P[prd]
+  P --> S[shard]
+  E -.->|low/medium complexity| Ad[adhoc]
+end
+
+subgraph Meso["Meso Layer — Issue Engineering"]
+  Pl[plan] --> T[tasks]
+end
+
+subgraph Micro["Micro Layer — Per-Task Loop"]
+  T --> Re1[red]
+  Re1 --> G1[green]
+  G1 --> J{judge}
+  J -->|violation| G1
+  J -->|pass| Rf[refactor]
+  Rf -.->|HITL Gate 3| Done[merged]
+end
+
+subgraph MicroAlt["Micro Layer — Direct Path (low-complexity tasks)"]
+  T -.->|complexity ≤ 3| Ex[execute]
+end
+
+style F fill:#f5e1f5
+style A fill:#f5e1f5
+style R fill:#f5e1f5
+style E fill:#e1f5e1
+style Re fill:#e1f5e1
+style P fill:#e1f5e1
+style S fill:#e1f5e1
+style Ad fill:#e1f5e1
+style Pl fill:#e1e7f5
+style T fill:#e1e7f5
+style Re1 fill:#f5e1e1
+style G1 fill:#f5e1e1
+style J fill:#f5e1e1
+style Rf fill:#f5e1e1
+style Ex fill:#f5e1e1
+```
+
+### Workflow at a Glance
+
+| Phase | Slash command | Artifact committed | What the human reviews / decides |
+|-------|---------------|--------------------|----------------------------------|
+| **Bootstrap · Setup** | `deviate setup [--agent <name>]` | `.deviate/config.toml`, default execution-layer packs (macro + meso + micro, including `deviate-init`), shared `deviatdd` skill, selected-agent `/deviate-*` commands | Confirm the one agent install. `--agent` skips only the agent picker. TTY still asks `[l]ocal/[g]lobal`, claim-remote `[y]es/[n]o` (default `n`), then a pack checklist (Enter = none). |
+| **Bootstrap · Init** | `/deviate-init` | `specs/constitution.md`, `mise.toml`, `specs/issues.jsonl` (skips files already present) | **First prompt after setup.** Pi: prompt template from `deviate-init.md` (not the `deviatdd` skill). Codex: the `deviate-init` skill. Optional no-agent path: `deviate init pre && deviate init post` (stages; does not commit). Empty `CLAUDE.md` / `AGENTS.md` after setup is expected. |
+| **Product · Flows** | `/deviate-flows` | `specs/_product/flows/flows-<domain>.md` + updated `specs/_product/flows/index.md` | Confirm the actor, job-to-be-done, and trigger are right; commit the flow file when asked. |
+| **Product · Architecture** | `/deviate-architecture` | `specs/_product/architecture.md`, `specs/_product/domain-model.md` | Reads existing flows; classify the change as Local / Context-Bridging / Context-Creating; commit when satisfied. |
+| **Product · Release** | `/deviate-release` | `specs/_product/release-next.md` (overrides previous) | Supply a release-goal sentence; confirm the Included Flows / Included Work / Acceptance tables reflect that goal; commit. |
+| **Macro · Explore** | `/deviate-explore` | `specs/{epic}/explore.md` (raw codebase scan — what exists, not what to do) | Does the scan cover the right subsystems? Commit to advance. |
+| **Macro · Research** *(Gate 1)* | `/deviate-research` | `specs/{epic}/design.md`, `specs/{epic}/data-model.md` | **Gate 1**: approve the design + data-model before PRD synthesis. |
+| **Macro · PRD** | `/deviate-prd` | `specs/{epic}/prd.md` (FR list + acceptance criteria) | Verify each FR is testable; commit. |
+| **Macro · Shard** | `/deviate-shard` | `specs/{epic}/issues/ISS-NNN-*.md` (one file per vertical slice), with `flow_refs:` frontmatter and embedded `## User Stories Ledger` / `## ATDD Acceptance Criteria` sections | Review every sharded issue for completeness, edge cases, and scope (soft review — the system auto-advances to Meso and does not block). Issues are born as full specs — the user-facing *spec content* is embedded here, but **claiming and worktree creation is a separate CLI step (`deviate specify`)** that runs after `/deviate-shard` and before the meso slash commands below. |
+| **Meso · Specify** | `deviate specify [ISS-NNN-NNN]` | A git worktree at `.worktrees/<branch>/` and a claim entry appended to `specs/issues.jsonl`. `claim_remote` defaults **false** (local only). Push-as-lock is opt-in (`--claim-remote` / `claim_remote = true`). | The setup step before plan/tasks. With no argument, auto-claims the next unblocked BACKLOG issue; with an explicit ID, claims that issue. Stops after the worktree is created — does NOT advance session state and does NOT run plan or tasks. `cd` into the printed worktree path before running any other meso slash command. Path A: `deviate meso run --no-setup --local` stays in this clone. |
+| **Run** *(full pipeline, end-to-end)* | `deviate run` | Worktree at `.worktrees/<branch>/`, `tasks.md`, `tasks.jsonl`, then completed task commits | The canonical "go do the next thing" command. Discovers the next BACKLOG issue, claims it (creating a per-issue worktree), runs SPECIFY → PLAN → TASKS in that worktree, then drains every PENDING task through the TDD cycle. Forwards `--profile` / `--no-judge` / `--no-refactor` / `--agent` / `--json` to the micro drain. Internally calls `deviate meso run` then `deviate micro run --all` inside the created worktree. |
+| **Meso · Plan** | `/deviate-plan` | `specs/{epic}/issues/ISS-NNN/plan.md` (per-issue localized research, workstation file structure) | **Must be invoked inside the worktree that `deviate specify` created.** Review the workstation mapping and the integration surface listed; commit. Optional when shard already embedded spec sections. |
+| **Meso · Tasks** | `/deviate-tasks` | `specs/{epic}/issues/ISS-NNN/tasks.md` + `specs/{epic}/tasks.jsonl` (append-only ledger) | **Must be invoked inside the same worktree.** The `tasks.md` artifact is the human's execution blueprint. Verify: 4–8 tasks per issue, every task has a Verification CLI command, each task declares a Mode (`TDD` or `IMMEDIATE`) and Type, DAG `blocked_by` deps are right. TDD tasks flow to red→green→judge→refactor; IMMEDIATE tasks route to `/deviate-execute`. |
+| **Micro · Red** | `/deviate-red <task-id>` | A failing test (no production code) | Agent-internal; you see the test on commit. |
+| **Micro · Green** | `/deviate-green <task-id>` | Production code that passes the test | Agent-internal; GREEN is constrained to `src/` + permitted paths, and JUDGE checks scope before advancing. |
+| **Micro · Judge** | `/deviate-judge <task-id>` | A `JUDGE_PASS` or `JUDGE_REJECTED` verdict over the GREEN diff | On rejection, the **Green → Judge → Green loop** rolls back to the RED commit, injects `<train_feedback>` into the next GREEN, and retries (up to 3 attempts). Read the feedback — it's the only signal you'll get for what the compliance checker objected to. |
+| **Micro · Refactor** | `/deviate-refactor <task-id>` | Polished, behavior-preserving code (only on `JUDGE_PASS`) | If the refactor breaks tests, the CLI discards it and the task completes on the verified GREEN. |
+| **Micro · Execute** | `/deviate-execute <task-id>` | A targeted change for `direct` / `e2e` tasks | Skips the TDD cycle; still has its own JUDGE pass. |
+| **Micro · Run** *(agent-internal drain)* | `deviate micro run [task-id] --all` | Completed task commits per the cycle | Agent-internal dispatch — `deviate micro run <task-id>` runs a single task; `deviate micro run --all` drains every PENDING task. Top-level `deviate run` invokes this with `--all` inside the worktree the meso step just created. Forwards `--profile` / `--no-judge` / `--no-refactor` / `--agent` / `--json`. |
+| **Release** | `/deviate-pr <task-id>` | A conventional-commit PR | Optional pack. Open the PR; on merge, the issue ledger is appended with `COMPLETED`. |
+| **Release** *(Gate 3)* | `/deviate-review` | Comments-only PR scan (optional pack) | **Gate 3**: comments only by default (stdout / GitHub COMMENT). Not a merge gate. Opt-in `--apply` is CRITICAL-only. |
+| **Walkthrough** | `/deviate-walkthrough` | Four-look map (optional pack; no commit) | Brief location, test hunks, production hunks vs named checks, command to run those checks. Does not approve or auto-edit. |
+| **Cleanup** | `/deviate-prune` | Spy/impl tests thinned; `plan.md` / `tasks.md` and JSONL ledgers unchanged | Manual honeycomb pass for **one** issue. Drops `spy` / `impl` (marks, name tags, or untagged internal probes); keeps `behavioral` / `ac` and public input-to-output. Never deletes `plan.md`, `tasks.md`, `explore.md`, `prd.md`, or `issues/*.md`. Never touches `issues.jsonl`, `tasks.jsonl`, or `flows.jsonl`. Manual invoke only — not hooked into COMPLETED, `--all`, or the skill success loop. |
+
+Operational tools (no gate): `/deviate-triage`, `/deviate-constitution`, `/deviate-hotfix`. `/deviate-prune` is the manual honeycomb test-thinning surface (thin CLI `deviate prune pre` / `post`; the slash command commits the cleanup).
+
+---
+
+## Phase transparency
+
+`--help` and this table say which phases **commit**, **spawn an agent**, or **fail closed**. `pre` injects a JSON contract to the agent; `post` validates, writes, and often commits (you did not type `git commit`). Slash prompts tell the agent to run `pre`/`post`; auto prompts tell the agent not to — the orchestrator does. Codex spawn is `codex exec --sandbox workspace-write --ask-for-approval never` (`src/deviate/core/agent.py`). `meso run` and `micro run` nest that spawn.
+
+Default setup installs **macro + meso + micro** plus the shared `deviatdd` skill. Optional packs stay off until selected: `product` (bundle), `merge`, `pr`, `review`, `walkthrough`, `html`, `hotfix`, `triage`, `prune`, `e2e`.
+
+| Phase | Does | Commits | Debug a fail |
+|-------|------|---------|--------------|
+| **setup** | Writes `.deviate/`, persists one agent, installs default packs + `deviatdd`. `claim_remote` defaults **false**. `--agent` skips only the agent picker. | No. | Non-TTY without `--agent` → `NO_AGENT_SELECTED`. Unknown `--packs` → fail closed. Named agent missing → `AGENT_NOT_INSTALLED`. |
+| **adhoc** | One spec-enriched issue + `FR-ADHOC-NNN` + a BACKLOG ledger row. | Yes — `post` commits artifacts. Record stays BACKLOG. | Missing problem statement; complexity HIGH without `--force`. |
+| **meso** | Default: worktree + claim, then PLAN → TASKS (spawns the agent). Path A: `deviate meso run --no-setup --local` stays in this clone and skips the remote lock. | Yes — claim, `plan post`, `tasks post`. | `MESO_PLAN_INVALID`, `MESO_TASKS_INVALID`, `NO_CLAIMABLE_ISSUES`. |
+| **micro** | RED → GREEN → JUDGE → REFACTOR (or EXECUTE). Spawns the agent each phase. `--profile fast` skips **JUDGE and REFACTOR**. `deviate micro run --review` is a **TTY pause before the phase commit**, not `/deviate-review`. Skill argument `review` is an agent loop policy — never pass `--review` from the skill. | Yes — each phase. RED uses `git commit --no-verify`. | `REVIEW_REQUIRES_TTY`, `TRAIN_EXHAUSTED`, `COMMIT_FAILED`. `NO_PENDING_TASKS` (exit 1) means the queue is empty. |
+| **review** | Optional pack. `/deviate-review` is **comments-only** by default. Not a merge gate. | No (unless opt-in `--apply` landed a CRITICAL fix). | Missing named checks → `brief incomplete`. Unclaimed plan ACs stay comment input (`uncovered`); not a fail-close. |
+| **walkthrough** | Optional pack. Four-look map: brief location, test hunks, production hunks vs named checks, command to run those checks. | No. | Missing brief / named checks: stop. |
+
+Why each phase exists — and the research citations — live in [`docs/rationale.md`](docs/rationale.md).
+
+---
+
+## Troubleshooting
+
+**`uv: command not found`** — Install [uv](https://docs.astral.sh/uv/) first
+(it's the project's mandated package manager per
+[`specs/constitution.md`](specs/constitution.md)). macOS / Linux:
+`curl -LsSf https://astral.sh/uv/install.sh | sh`.
+
+**`deviate: command not found` after `uv tool install deviatdd`** — Verify
+the install landed: `uv tool list | grep deviatdd`. Reinstall if missing:
+`uv tool install --reinstall deviatdd`. The PyPI package name and the CLI
+binary name differ — that's intentional (see [Quickstart](#quickstart)).
+
+**`deviate setup` runs but `/deviate-*` commands don't appear in the
+agent** — Slash commands are installed to `<workdir>/.claude/commands/`,
+`.opencode/commands/`, `.omp/commands/`, `.factory/commands/`,
+`.pi/prompts/`, and (Pi global) `~/.pi/agent/prompts/`. Verify the
+directory exists and is readable, then restart the agent so it picks up
+the new commands.
+
+**Empty `CLAUDE.md` / `AGENTS.md` after setup** — Expected. Setup creates
+the files (and the symlink) but does not seed project guidance. Init
+scaffolds `specs/constitution.md`, `mise.toml`, and `specs/issues.jsonl`.
+
+**`--agent` did not skip the local/global, lock, or pack prompts** —
+`--agent` skips **only** the agent picker. Use
+`--agent-export-mode local|global --packs none --no-claim-remote` to skip
+the TTY extras.
+
+**`/deviate-plan` (or `/deviate-tasks`) picks up the wrong issue, claims
+"no active issue", or shows stale context** — Meso slash commands must be
+invoked from inside the per-issue worktree that `deviate specify` (or
+`deviate run`) created. From the main checkout, run `deviate specify`
+(or `deviate specify ISS-NNN-NNN` for a specific issue), `cd` into the
+`.worktrees/<branch>/` path it prints, and re-open the agent there
+before running `/deviate-plan` or `/deviate-tasks`.
+
+**`mise run publish` fails with `PYPI_API_TOKEN is not set`** — The task
+loads `.env` from the project root. `.env` must contain
+`PYPI_API_TOKEN=pypi-...`. `.env.example` documents the variable name;
+`.env` itself is gitignored.
+
+**Agent backend not installed** — `deviate setup --agent <name>` scaffolds
+the project without the agent present, but invoking `/deviate-*` slash
+commands requires the agent to be installed. Install Claude Code / OpenCode
+/ Pi / Droid / Factory / OMP first per their respective install
+instructions.
+
+For development-setup details, see
+[`CONTRIBUTING.md`](CONTRIBUTING.md#development-setup) and
+[`specs/constitution.md`](specs/constitution.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Werner Bisschoff