deviatdd 2.5.4__tar.gz → 2.7.2__tar.gz

{deviatdd-2.5.4 → deviatdd-2.7.2}/CHANGELOG.md

@@ -6,6 +6,86 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Changed
+- **`deviate run` is now a full-pipeline orchestrator; per-task dispatch moved to `deviate micro run`.**
+  The top-level `deviate run` command now does both `deviate meso run` and
+  then runs `deviate micro run --all` inside the worktree the meso step just
+  created. The previous per-task / `--all` task dispatcher that used to live
+  as top-level `deviate run` was relocated to `deviate micro run [task-id]`
+  / `deviate micro run --all`. The new orchestrator supports `--issue`,
+  `--force`, `--profile`, `--no-judge`, `--no-refactor`, `--agent`, and
+  `--json`. The top-level command remains in the "Run by you (start here)"
+  panel as the canonical "go do the next thing" entry point; `deviate micro`
+  joined the agent-internal panel alongside `red`/`green`/`judge`/etc.
+  `_meso_run` now returns the created worktree path so the orchestrator
+  can `chdir` into it without re-deriving the path from the ledger; the
+  session's `last_command` is rewritten to the micro subcommand form when
+  the orchestrator hands off. (`src/deviate/cli/__init__.py`,
+  `src/deviate/cli/micro.py`, `src/deviate/cli/meso.py`,
+  `tests/test_cli/test_help.py`, `tests/test_cli/test_micro.py`,
+  `tests/test_micro/test_run.py`, `tests/test_micro/test_orchestration.py`,
+  `tests/test_cli/test_top_level_run.py`, `README.md`,
+  `specs/DeviaTDD-api.md`, `specs/DeviaTDD-architecture.md`,
+  `specs/implementation-gap.md`, `src/deviate/ui/pipeline.py`,
+  `src/deviate/prompts/commands/deviate-{walkthrough,review}.md`.)
+
+- **`deviate meso run` default output no longer dumps `_plan_pre` / `_tasks_pre` JSON contracts.**
+  Those pre subcommands `print()` their JSON contract on stdout for the
+  agent-subprocess CLI workflow (`deviate plan pre` / `deviate tasks pre`).
+  When the in-process `_meso_run` parent invoked them directly, the JSON
+  leaked onto the user's terminal alongside the useful
+  `WORKTREE` / `SPEC_DISCOVERED` lines. A small `_silence_stdout` helper
+  captures and discards stdout around the two calls; rich console output
+  is unaffected, and the `deviate plan pre` / `deviate tasks pre` CLI
+  paths (which route through `@with_json_quiet`) are unchanged.
+  (`src/deviate/cli/meso.py`, `tests/test_meso/test_meso_orchestration.py`.)
+
+- `deviate-review` prompt v3.0.0: reframed as JUDGE-aware review. Three domains
+  (Clean Code, Constitution, PRD Alignment) downgraded to light-sniff — cross-task
+  only, no re-reading governance files. Domain 3 renamed to "Pragmatism &
+  Architectural Coherence" with 6 new cross-task checks. Added strategy-gated
+  review (full/diff_first/targeted), finding classification with Severity +
+  Confidence, and machine-parseable Fix Instructions block. Flow Coverage
+  domain made diff-only to match JUDGE-aware posture. (PR #?.)
+- `deviate-review` prompt v3.1.0: STEP 4 now autonomously applies
+  `[CRITICAL]` and `[SUGGESTION]` fixes from the Quick Fix Summary
+  (deterministic selection rule — no `ask` tool, no HITL choice prompt),
+  runs the project's aggregate validation gate, then commits the result
+  with a Conventional Commit subject
+  (`🐛 fix(review): apply N post-review fixes for {ISSUE_ID}`). Explicit
+  `git add -- <files>` (never `git add -A`) keeps the advisory report at
+  `.deviate/review/reports/` unstaged. `[OPPORTUNITY]` items remain
+  deferred to a future slice. Pre-commit and pre-push hooks remain
+  non-bypassable (`--no-verify` is never used); aggregate validation
+  failure reverts every fix via `git restore .` before aborting.
+- `/deviate-walkthrough` prompt v1.1.0: enforces true one-section-per-turn cadence. The prompt's STEP 4 previously said "then (optionally) ask a structured question" and the ADHD-friendly laws said sections "may include an `ask`" — both wordings gave the agent permission to skip interactive questioning and dump the entire walkthrough in a single response, defeating the HITL Gate 3 design intent. Replaced with mandatory per-section `ask`, an explicit "Two sections in one response is a bug" rule, a renumbered Law #5 ("One section per turn"), a "When to ask — always" rule that removes the old escape hatch, and an explicit override of universal invariant #1 (the "Automated Execution" no-questions rule) so the HITL gate's interactive posture wins. The `ask` is the pacing mechanism — a two-option "Clear? / Next section →" is a valid gate, even on awareness-only sections.
+### Fixed
+- `deviate micro run --all` no longer segfaults during the JUDGE phase when GREEN
+  fails to deliver passing tests. Root cause: the background-thread reader in
+  `_invoke_streaming` called `c.file.flush()` which bypassed Rich's RLock and
+  raced with main-thread `c.print` writes on `sys.stdout.fileno()`. Removed the
+  flush — both threads now only write through `c.print()`, which Rich
+  serializes internally via its own RLock on the shared Console instance.
+  (The `stdout_lock` in `_make_output_handler` already serialized the handler
+  body against `emit_jsonl` and remains in place for that purpose.)
+- Background-thread pipe I/O errors in `_invoke_streaming` no longer surface a
+  CPython 3.13 `KeyError` traceback ("Exception ignored in thread ... read_stderr")
+  during agent subprocess shutdown. Both `read_stdout` and `read_stderr` now
+  catch pipe-closure exceptions (`ValueError`, `OSError`); `read_stdout` also
+  sets `stdout_done = True` in a `finally` block so the caller doesn't raise a
+  false `AgentTimeoutError` when the pipe closes concurrently with the timeout
+  branch. The thread still terminates correctly; losing residual stderr is
+  harmless because the manifest comes from stdout.
+  (`src/deviate/core/agent.py`.)
+- Worktrees created by `deviate meso run` now receive the `.pi/` and `.omp/`
+  skill directories alongside `.claude/`, `.opencode/`, and `.factory/`.
+  Root cause: `_sync_agent_dirs_to_worktree` in `src/deviate/cli/meso.py`
+  iterated a hardcoded `_AGENT_DIRS` tuple that pre-dated the pi/omp
+  agent platforms, while `deviate setup`, `detect_agents`, and the
+  `.gitignore` patterns in `cli/__init__.py` already targeted all five
+  — so users on those platforms had to re-run `deviate setup` inside
+  every worktree. Added `.pi` and `.omp` to `_AGENT_DIRS` and updated
+  the docstring; added a regression test pinning the sync list.
 ### Added
 - PyPI-ready `pyproject.toml` metadata: `readme`, `license = "MIT"` (SPDX),
   `authors`, `keywords`, `classifiers` (incl. `License :: OSI Approved :: MIT
@@ -21,6 +101,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   unset. A new `.env.example` documents the variable; `.env` is gitignored
   via a pattern that ignores `.env` and `.env.*` while keeping
   `.env.example` trackable.
+- `/deviate-walkthrough` slash command: human-guided architectural walkthrough
+  that curates the diff by concern (DEEP_DIVE / NOTE / SKIM / SKIP triage),
+  asks structured yes/no or multiple-choice questions via the `ask` tool with
+  a recommended default, and surfaces architectural decisions missed by
+  automated phases. Includes `deviate walkthrough pre/post` CLI backend.
+  (PR #?.)
 - Security: `mise run publish` passes the token via `UV_PUBLISH_TOKEN`
   inline-prefix env var (`UV_PUBLISH_TOKEN="$PYPI_API_TOKEN" uv publish
   dist/*`) instead of the `--token` CLI flag. The inline form scopes the
@@ -65,7 +151,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `test_module_version_resolves` import-time guard fails loudly if the
   module-level lookup regresses.
 
+:- CLI run output cleaned up: removed redundant "Processing TSK-..." line
+  (the rich phase panel already shows task identity), added missing
+  JUDGE phase panel/block to the execute-phase path, and fixed
+  duplicate JUDGE → text in the TDD-cycle path.
 ### Changed
+- `deviate --help` now renders three Typer help panels instead of a flat
+  command list. **"Run by you (start here)"** is the human entry point —
+  `setup` (with `Bootstrap a new project with DeviaTDD (start here).`),
+  `run` (with `Use \`deviate run --all\` to drain the queue.`), and `meso`
+  (with `Use \`deviate meso run\` to run the automated setup → plan →
+  tasks pipeline`) — `run` and `meso` are surfaced in the panel by name
+  with their literal invocation, since `run --all` and `meso run` are the
+  actual entry points. **"Agent/internal (via /deviate-* slash
+  commands)"** lists every phase dispatcher (`specify`, `plan`, `tasks`,
+  `pr`, `merge`) and Typer group (`explore`, `research`, `prd`, `shard`,
+  `macro`, `adhoc`, `red`, `green`, `judge`, `refactor`, `execute`, `e2e`,
+  `hotfix`, `init`, `constitution`, `review`) the agent drives; first-
+  timers see that those commands are not for them. **"Optional / manual
+  utilities"** holds `feature` (create a branch) and `inspect` (list
+  issue/task ledgers) — useful but not on the standard path. Each
+  agent-internal command gained a one-line description (e.g. `Macro:
+  codebase exploration`, `Micro: write a failing test`, `Final PR review
+  (Gate 3)`) so the panel reads as a glossary, not a wall of names. The
+  `run_command` docstring (`src/deviate/cli/micro.py`) was rewritten to
+  lead with the `--all` invocation. Backed by
+  `tests/test_cli/test_help.py`, which pins panel names, membership,
+  ordering, and the literal meso/run invocations so the first-timer
+  wording can't regress.
 - **Shard prompts now own all vertical-slicing rules**; the PRD prompt's
   §Issue Sharding Strategy was removed to eliminate drift between the two.
   `src/deviate/prompts/commands/deviate-shard.md` (v1.1.0) now hard-enforces
@@ -113,6 +226,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Previously it only updated the ledger after an external merge. The `deviate
   merge` CLI command is unchanged — the prompt now drives it as a final step
   rather than relying on an external squash-merge tool.
+- Active domain discipline applied to `/deviate-research`, `/deviate-prd`, `/deviate-flows`, and `/deviate-architecture`. Each phase now actively term-challenges against the relevant glossary (`data-model.md`, `domain-model.md`, `flows-product.md`), sharpens fuzzy language, stress-tests with concrete scenarios, and updates the artifact inline as terms resolve. The macro-layer `interactive_hitl_gate_1` and the PRD `AMBIGUITY_INTERROGATION` gate now require a discipline pass before presenting HITL questions; the Product-layer discovery steps are upgraded from passive 3–4 bullet blocks to structured 7–8 bullet active disciplines. Spec alignment: `specs/DeviaTDD-architecture.md` §2.1 and §5.0, `specs/DeviaTDD-api.md` §1.5 and §2.
+- **Reworked `deviate meso run` and `deviate run --all` output** to a clean,
+  professional, rich-CLI format. New module `src/deviate/ui/pipeline.py`
+  ships five components — `PipelineBanner` (framed opening panel with
+  `MESO <issue_id>` and a `SPECIFY ▶ PLAN ▶ TASKS` step indicator),
+  `PhaseCallout` (per-phase rounded panel with `◐`/`●`/`✗` markers and
+  elapsed time), `RunBoard` (multi-column Rich `Table` updated in place
+  by the `OrchestrationMonitor` event stream), `TrainIndicator`
+  (sequential `● 1/3 ─▶─ ◐ 2/3 ─▶─ ○ 3/3` retry visual), and
+  `PipelineSummary` (closing totals / duration / status panel). The
+  `OrchestrationMonitor` gained an optional `board` parameter that
+  updates the board on every `phase_change` / `task_completed` /
+  `task_failed` event. All literal tokens the existing test suite
+  asserts against (`RED`, `GREEN`, `COMPLETED`, `JUDGE_REJECTED`,
+  `TRAIN`, `MESO`, `IDLE`, `DISCOVERED`, `INVOKE_AGENT`, `DRY_RUN`,
+  `NO_CLAIMABLE_ISSUES`, `ISSUE_COMPLETED`, `INVALID_ISSUE_ID`,
+  `BLOCKED`, `PROGRESS_RESET`, `TASK_ALREADY_DONE`, `TEST_FAILURE`,
+  `JUDGE_AGENT_NO_FEEDBACK`, `<PHASE>_FAILED`, etc.) are preserved
+  verbatim in the output — the framed panels are additive, not
+  replacements. Aesthetic: "Editorial / Refined Engineering" — restrained
+  palette (deep blue / semantic green-red-amber), heavy Unicode
+  box-drawing (`╭╮╰╯│─`), monospace tabular layout. 46 new tests in
+  `tests/test_ui/test_pipeline.py` pin the visual contract. Spec
+  alignment: `specs/DeviaTDD-api.md` §5.2 (`deviate run --all`) and §5.3
+  (`deviate meso run`) document the new output structure.
 
 ### Fixed
 - `resolve_issue_record` and `_deduplicate_issues` now treat `COMPLETED`

{deviatdd-2.5.4 → deviatdd-2.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deviatdd
-Version: 2.5.4
+Version: 2.7.2
 Summary: DeviaTDD CLI — agent orchestration framework
 Project-URL: Homepage, https://github.com/wernerbisschoff/deviatdd
 Project-URL: Repository, https://github.com/wernerbisschoff/deviatdd
@@ -157,8 +157,28 @@ Once setup is done, drive the entire lifecycle from inside your agent. Each phas
 /deviate-review                          # ← Gate 3: final PR scan; merge or request changes
 ```
 
-The full lifecycle takes you from a problem statement to merged, tested code with a documented audit trail.
+**Or, run the whole pipeline in one command** — the top-level
+`deviate run` is the canonical "go do the next thing" entry point. 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:
+
+```
+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/werner-bisschoff/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, Three Gates
@@ -226,6 +246,7 @@ style Ex fill:#f5e1e1
 | **Macro · PRD** | `/deviate-prd` | `specs/{epic}/prd.md` (FR list + acceptance criteria) | Verify each FR is testable; commit. |
 | **Macro · Shard** *(Gate 2)* | `/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 | **Gate 2**: read every sharded issue for completeness, edge cases, and scope. Issues are born as full specs — there is no separate specify step. |
 | **Macro · Adhoc** *(shortcut)* | `/deviate-adhoc` | `specs/adhoc/ISS-ADH-NNN-*.md` (single issue, spec-enriched) | Use for low/medium-complexity tasks; the complexity classifier auto-routes high-complexity work to the full Macro path. |
+| **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) | 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) | 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. |
@@ -233,6 +254,7 @@ style Ex fill:#f5e1e1
 | **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 | Open the PR; on merge, the issue ledger is appended with `COMPLETED`. |
 | **Release** *(Gate 3)* | `/deviate-review` | Final PR scan | **Gate 3**: merge or request changes. |
 

{deviatdd-2.5.4 → deviatdd-2.7.2}/README.md

@@ -103,8 +103,28 @@ Once setup is done, drive the entire lifecycle from inside your agent. Each phas
 /deviate-review                          # ← Gate 3: final PR scan; merge or request changes
 ```
 
-The full lifecycle takes you from a problem statement to merged, tested code with a documented audit trail.
+**Or, run the whole pipeline in one command** — the top-level
+`deviate run` is the canonical "go do the next thing" entry point. 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:
+
+```
+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/werner-bisschoff/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, Three Gates
@@ -172,6 +192,7 @@ style Ex fill:#f5e1e1
 | **Macro · PRD** | `/deviate-prd` | `specs/{epic}/prd.md` (FR list + acceptance criteria) | Verify each FR is testable; commit. |
 | **Macro · Shard** *(Gate 2)* | `/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 | **Gate 2**: read every sharded issue for completeness, edge cases, and scope. Issues are born as full specs — there is no separate specify step. |
 | **Macro · Adhoc** *(shortcut)* | `/deviate-adhoc` | `specs/adhoc/ISS-ADH-NNN-*.md` (single issue, spec-enriched) | Use for low/medium-complexity tasks; the complexity classifier auto-routes high-complexity work to the full Macro path. |
+| **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) | 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) | 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. |
@@ -179,6 +200,7 @@ style Ex fill:#f5e1e1
 | **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 | Open the PR; on merge, the issue ledger is appended with `COMPLETED`. |
 | **Release** *(Gate 3)* | `/deviate-review` | Final PR scan | **Gate 3**: merge or request changes. |
 

{deviatdd-2.5.4 → deviatdd-2.7.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deviatdd"
-version = "2.5.4"
+version = "2.7.2"
 description = "DeviaTDD CLI — agent orchestration framework"
 readme = "README.md"
 license = "MIT"

{deviatdd-2.5.4 → deviatdd-2.7.2}/specs/DeviaTDD-api.md

@@ -28,8 +28,10 @@ scripts. All commands are registered in `src/deviate/cli/__init__.py` using Type
   project-specific test/lint/format/setup/dev commands, ensures a symlink
   relationship between `CLAUDE.md` and `AGENTS.md` (via
   `_linkify_governance_files`), applies governance blocks to the canonical
-  file, and installs the DeviaTDD prompt commands (currently
-  24 flat `.md` files: 24 `deviate-*`) into **all five** supported agent
+  file, and installs the DeviaTDD prompt commands. Currently 25 `deviate-*`
+  slash commands + 1 standalone `tools-mcp-servers` command (for Factory Droid)
+  — 26 flat `.md` files total — are installed to `.{agent}/commands/` (or
+  `.{agent}/prompts/` for Pi) during `deviate setup`. Commands land in all agent
   directories — `.claude/commands/`, `.opencode/commands/`,
   `.factory/commands/`, `.pi/prompts/`, `.omp/prompts/` — in a single invocation, regardless of which agent was passed
   via `--agent`. Each command is a flat `<name>.md` file with a minimal YAML
@@ -151,6 +153,8 @@ The Product layer ships as **agent skills** (no dedicated CLI subcommands) — t
 
 **Downstream consumption:** `deviate-shard` and `deviate-adhoc` SKILL.md bodies read `specs/_product/flows/`, `specs/_product/release-next.md`, `specs/_product/architecture.md`, and `specs/_product/domain-model.md` as authoritative context. Each sharded or adhoc issue emits a `flow_refs: [FLOW-XX, ...]` field in its YAML frontmatter and in the `IssueRecord.flow_refs` ledger entry (validated against `^FLOW-\d{2,}$`), so vertical slices stay traceable back to the flow that motivated them. `deviate adhoc pre` accepts a `--flow-ref FLOW-01,FLOW-02` CLI override to set the flow refs explicitly when the agent's natural-language inference is ambiguous.
 
+**Active Domain Discipline** is enforced at HITL gates: the Product-layer discovery steps (`/deviate-flows`, `/deviate-architecture`) follow a structured 7–8 bullet active discipline — one question at a time with a recommended answer, dependency-ordered, read-first, term-challenge against the glossary, sharpen fuzzy language, stress-test with scenarios, and update the artifact (`flows-<domain>.md` or `domain-model.md`) inline as terms resolve.
+
 #### `/deviate-shard` (Macro Layer)
 
 * **Objective:** Decomposes the PRD into standalone, testable issue files.
@@ -170,6 +174,8 @@ All macro-layer commands follow the `pre`/`post` subcommand pattern (except `ini
 Every `pre` subcommand accepts `--json` (emit JSON contract to stdout) and `--quiet`
 (suppress diagnostic output).
 
+**Active Domain Discipline** is enforced at HITL gates: the macro phases that interact with the human (`/deviate-research` Gate 1, `/deviate-prd` Ambiguity Interrogation, `/deviate-shard` Gate 2) actively term-challenge against the upstream glossary, sharpen fuzzy language, stress-test with concrete edge-case scenarios, and update the relevant artifact (`design.md`, `data-model.md`, `prd.md`) inline as terms resolve — not as a passive sign-off step.
+
 #### `deviate explore pre <problem> [--slug]`
 
 * **Source:** `src/deviate/cli/macro.py`
@@ -459,57 +465,130 @@ accepts `--json` and `--quiet`. `pre` emits a JSON contract describing the envir
 
 ### 5. Automated Pipeline Orchestration
 
-#### `deviate run <task-id>`
-
-* **Source:** `src/deviate/cli/micro.py` (`_run_single`, `_dispatch_task`)
-* **Description:** Triggers the automated execution cycle for a single task node. Routes by
-  `execution_mode` (TDD or non-TDD). TDD mode runs the RED -> GREEN -> JUDGE -> REFACTOR
-  cycle. Non-TDD (`DIRECT` or `E2E`) runs `_run_execute_phase`, which
-  commits the work, then optionally runs a JUDGE pass against `spec.md` and rolls back
-  on `COMPLIANCE_VIOLATION` (up to `max_judge_attempts = 3`).
-* **Green → Judge → Green loop (TDD only):** `_run_tdd_cycle` wraps the GREEN→JUDGE pair in a `while not judge_passed` loop with up to `max_train_attempts = 3`. On test failure or `COMPLIANCE_VIOLATION`, `_execute_rollback()` runs `git reset --hard <red_sha>` against the RED-boundary SHA stored in `session.red_commit_sha` (captured at the end of the RED phase), the session is `force_transition_to("GREEN")`, and the previous attempt's feedback is injected as `<train_feedback>` into the next GREEN prompt via `_build_auto_prompt("green", ...) + "\n\n<train_feedback>\n{...}\n</train_feedback>\n"`. The cycle retries from GREEN. After 3 attempts the task is marked `FAILED` and the pipeline halts with `PhaseFailedError`. The feedback source precedence is `train_feedback` (preferred) → `violations` (structured list) → `rationale` → `summary` → fallback string.
-* **Resume from Mid-Phase:** If `session.current_phase` is `JUDGE` or
-  `REFACTOR` when invoked, the cycle resumes from that phase via the `start_phase`
-  parameter. IDLE / RED trigger a fresh cycle from RED.
+#### `deviate run` (Full-Pipeline Orchestrator)
+
+* **Source:** `src/deviate/cli/__init__.py` (top-level `run_command`)
+* **Description:** Canonical "go do the next thing" entry point. Chains the meso
+  pipeline (`deviate meso run`) with the micro drain (`deviate micro run --all`)
+  inside the worktree the meso step just created. Discovers the next unblocked
+  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 (or the direct-execute phase for IMMEDIATE-typed tasks). Internally:
+  1. Calls `_meso_run(issue_id=...)` from `src/deviate/cli/meso.py`, which returns
+     the created worktree path on success (`str(worktree_path)`).
+  2. `chdir`s into that worktree, updates `.deviate/session.json` to record the
+     `run --all` handoff, and calls `_run_all()` from `src/deviate/cli/micro.py`
+     to drain every PENDING task.
+  3. On hard failure (no worktree returned, worktree missing) prints a structured
+     error (`RUN_NO_WORKTREE` / `RUN_WORKTREE_MISSING`) and exits non-zero.
 * **Input Parameters:**
-  * `<task-id>` (Positional: `TSK-NNN-NN` format; omit to auto-select the first PENDING
-    task for the active issue)
+  * `--issue <ISS-NNN-NN>` (Target a specific BACKLOG issue; default: next unblocked)
+  * `--force` (Bypass `blocked_by` pre-flight guards; forwarded to meso)
+  * `--profile [full|fast|secure]` (Forwarded to the micro drain; resolved via
+    `resolve_profile()` from `src/deviate/core/profile.py`)
+  * `--no-judge`, `--no-refactor` (Composable boolean overrides for the profile;
+    forwarded to the micro drain)
+  * `--agent <name>` (Override agent backend for the micro phase)
+  * `--json` (Forward JSONL monitor events to stdout; suppresses Rich UI)
+* **Exit Codes:** 0 on full success; 1 if meso or micro reports failure.
+* **Replaces:** The old `deviate run <task-id>` and `deviate run --all`
+  task-dispatch surface. The per-task and `--all` dispatches now live at
+  `deviate micro run <task-id>` and `deviate micro run --all` respectively.
+
+#### `deviate micro run [task-id]` / `deviate micro run --all`
+
+* **Source:** `src/deviate/cli/micro.py` (`run_command` decorated by `micro_app`)
+* **Description:** The per-task / queue-drain dispatcher that used to live as the
+  top-level `deviate run`. Routes each task by `execution_mode` to the TDD cycle
+  (RED → GREEN → JUDGE → REFACTOR) or to the execute phase. Single-task by
+  default; `--all` drains every PENDING task for the active issue (or all
+  issues if no active issue is set).
+* **Single-Task (`deviate micro run <task-id>`):** Triggers the automated
+  execution cycle for a single task node. TDD mode runs the RED → GREEN →
+  JUDGE → REFACTOR cycle. Non-TDD (`DIRECT` or `E2E`) runs `_run_execute_phase`,
+  which commits the work, then optionally runs a JUDGE pass against `spec.md`
+  and rolls back on `COMPLIANCE_VIOLATION` (up to `max_judge_attempts = 3`).
+  Implements `_run_single` / `_dispatch_task` from `src/deviate/cli/micro.py`.
+  * **Green → Judge → Green loop (TDD only):** `_run_tdd_cycle` wraps the
+    GREEN → JUDGE pair in a `while not judge_passed` loop with up to
+    `max_train_attempts = 3`. On test failure or `COMPLIANCE_VIOLATION`,
+    `_execute_rollback()` runs `git reset --hard <red_sha>` against the
+    RED-boundary SHA stored in `session.red_commit_sha` (captured at the end of
+    the RED phase), the session is `force_transition_to("GREEN")`, and the
+    previous attempt's feedback is injected as `<train_feedback>` into the next
+    GREEN prompt via `_build_auto_prompt("green", ...) +
+    "\n\n<train_feedback>\n{...}\n</train_feedback>\n"`. The cycle retries from
+    GREEN. After 3 attempts the task is marked `FAILED` and the pipeline halts
+    with `PhaseFailedError`. The feedback source precedence is `train_feedback`
+    on the manifest → `_extract_judge_feedback(...)` from `tasks.md` → verbatim
+    verdict / rationale.
+  * **Resume from Mid-Phase:** If `session.current_phase` is `JUDGE` or
+    `REFACTOR` when invoked, the cycle resumes from that phase via the
+    `start_phase` parameter. IDLE / RED trigger a fresh cycle from RED.
+* **Queue Drain (`deviate micro run --all`):** **Issue-scoped** task sweep.
+  Resolves the active issue from `session.active_issue_id` (falling back to
+  branch-derived detection via the `feat/{epic}/{issue}` regex against
+  `specs/issues.jsonl`), then dispatches **every PENDING task for that issue**
+  sequentially. Each task gets up to **2 retry attempts**
+  (`_execute_task_with_retry`, `for attempt in range(2)`) before being marked
+  `FAILED` in the issue-scoped `tasks.jsonl`. The pipeline **halts on the first
+  failure** (`any_failed = True; break`) and exits with code `1`. If no
+  `active_issue_id` is set and the branch cannot resolve an issue, no tasks are
+  dispatched. Implements `_run_all` from `src/deviate/cli/micro.py`.
+  * **Train Retry Loop (per task):** Inside each task's TDD cycle,
+    `_run_tdd_cycle` allows up to **3 train attempts** (`max_train_attempts = 3`)
+    when GREEN tests fail or JUDGE returns `COMPLIANCE_VIOLATION`. Each train
+    attempt injects `<train_feedback>` from the previous attempt's failure
+    output back into the GREEN prompt and re-runs GREEN. Exhaustion raises
+    `PhaseFailedError`.
+  * **Graphite Integration:** If `.deviate/config.toml` contains
+    `graphite = true`, after each successful task the runner invokes
+    `gt create -m "feat({TSK}): {description}"` to spin up a stacked branch for
+    the next task.
+  * **Dashboard / Output:** Constructs an `OrchestrationMonitor` (in
+    `src/deviate/ui/monitor.py`) wired to a `RunBoard`
+    (`src/deviate/ui/pipeline.py`) with `total_tasks` set to the pending count.
+    The RunBoard renders as a multi-column Rich `Table` whose rows are updated
+    in place via the monitor's event stream (`task_started` / `phase_change` /
+    `task_completed` / `task_failed`). Output structure:
+    * **Run header panel** — `RUN <issue_id> N pending task(s)` in a framed panel.
+    * **Per-phase callouts** — Each `RED` / `GREEN` / `JUDGE` / `REFACTOR` /
+      `EXECUTE` phase emits a `PhaseCallout` (rounded `╭─╮` panel) with the
+      phase tag, task ID, status marker (`◐` in-progress, `●` completed,
+      `✗` failed), and elapsed time. The original token-bearing line
+      (`RED →`, `GREEN →`, etc.) is preserved alongside for backwards-compat
+      with existing tooling.
+    * **Train retry indicator** — On each `_run_tdd_cycle` retry, a
+      `TrainIndicator` renders the current attempt against the maximum
+      (`● 1/3 ─▶─ ◐ 2/3 ─▶─ ○ 3/3`). The literal `TRAIN` token is preserved.
+    * **Final RunBoard snapshot** — A full re-render of the board reflecting the
+      post-run state of every task (markers + per-row error reasons).
+    * **Pipeline summary** — A `PipelineSummary` panel with totals
+      (`Total tasks`, `Completed`, `Failed`, `Duration`, `Status`).
+    In `--json` mode the same monitor emits JSONL events
+    (`task_started`, `phase_change`, `task_completed`, `task_failed`,
+    `pipeline_halted`, `pipeline_complete`); the rich board panels are
+    suppressed in JSON mode. Agent output is forwarded to the monitor via a
+    streaming callback.
+* **Input Parameters:**
+  * `[task-id]` (Positional: `TSK-NNN-NN` format; omit to auto-select the first
+    PENDING task for the active issue; mutually exclusive with `--all`)
+  * `--all` (Drain every PENDING task for the active issue)
   * `--profile [full|fast|secure]` (Defaults to `full`):
     * `full` — RED + GREEN + JUDGE + REFACTOR (complete cycle)
     * `fast` — RED + GREEN only (skip JUDGE + REFACTOR)
     * `secure` — RED + GREEN + JUDGE (skip REFACTOR)
     * Boolean flags `--no-judge` / `--no-refactor` retained as composable overrides
-  * `--agent` (Override agent backend; falls back to `[agent].backend` in
+  * `--agent <name>` (Override agent backend; falls back to `[agent].backend` in
     `.deviate/config.toml`)
   * `--dry-run` (Print the resolved task and exit without dispatching)
-* **Common Flags:** `--json`, `--quiet`
+  * `--json`, `--quiet`, `--verbose`
 
-#### `deviate run --all`
-
-* **Source:** `src/deviate/cli/micro.py` (`_run_all`)
-* **Description:** **Issue-scoped** task sweep. Resolves the active issue from
-  `session.active_issue_id` (falling back to branch-derived detection via the
-  `feat/{epic}/{issue}` regex against `specs/issues.jsonl`), then dispatches **every
-  PENDING task for that issue** sequentially. Each task gets up to **2 retry attempts**
-  (`_execute_task_with_retry`, `for attempt in range(2)`) before being marked `FAILED` in
-  the issue-scoped `tasks.jsonl`. The pipeline **halts on the first failure**
-  (`any_failed = True; break`) and exits with code `1`. If no `active_issue_id` is set
-  and the branch cannot resolve an issue, no tasks are dispatched.
-* **Train Retry Loop (per task):** Inside each task's TDD cycle, `_run_tdd_cycle` allows
-  up to **3 train attempts** (`max_train_attempts = 3`) when GREEN tests fail or JUDGE
-  returns `COMPLIANCE_VIOLATION`. Each train attempt injects `<train_feedback>` from
-  the previous attempt's failure output back into the GREEN prompt and re-runs GREEN.
-  Exhaustion raises `PhaseFailedError`.
-* **Graphite Integration:** If `.deviate/config.toml` contains `graphite = true`, after
-  each successful task the runner invokes `gt create -m "feat({TSK}): {description}"`
-  to spin up a stacked branch for the next task.
-* **Dashboard / Output:** Constructs an `OrchestrationMonitor` with `total_tasks` set to
-  the pending count. The monitor emits live Rich dashboard events (task markers, phase
-  transitions) in TTY mode and JSONL events (`task_started`, `phase_change`,
-  `task_completed`, `task_failed`, `pipeline_halted`, `pipeline_complete`) when
-  `--json` is passed. Agent output is forwarded to the monitor via a streaming callback.
-* **Accepts:** `--profile [full|fast|secure]`, `--agent <name>`, `--json`, `--quiet`,
-  `--dry-run` (prints all resolved pending tasks and exits without dispatching).
+> **Note on the `last_command` field:** When the orchestrator hands off to
+> `micro run --all`, the session's `last_command` is rewritten to
+> `micro run [task-id] --all` (i.e. the micro subcommand path, not the
+> top-level `deviate run`), so the session always records the most
+> specific command that last touched it.
 
 #### `deviate meso run` (Automated Meso Pipeline)
 
@@ -548,6 +627,15 @@ accepts `--json` and `--quiet`. `pre` emits a JSON contract describing the envir
   aborts with `<PHASE>_FAILED`. Re-running the pipeline re-processes plan.md and tasks.md
   (no phase-skip logic); commits are skipped when there are no changes. The
   `UPSTREAM_MISSING` token is **not** emitted by the current implementation.
+* **Output:** The pipeline prints a `PipelineBanner` (`src/deviate/ui/pipeline.py`)
+  framed opening panel showing `MESO <issue_id> <issue_title>`, the epic / issue
+  slugs, and a horizontal step indicator (`SPECIFY ▶ PLAN ▶ TASKS`). On
+  completion it prints a `PipelineSummary` (totals + duration + `Status` row)
+  followed by a footer line `MESO pipeline complete - session at IDLE`. The
+  literal tokens `MESO`, `IDLE`, `DISCOVERED`, `INVOKE_AGENT`, `DRY_RUN`,
+  `NO_CLAIMABLE_ISSUES`, `ISSUE_COMPLETED`, `INVALID_ISSUE_ID`, `BLOCKED`,
+  `PROGRESS_RESET`, and `<PHASE>_FAILED` are all preserved in the output
+  for backwards-compat with existing tooling and the test suite.
 
 #### `deviate macro run` (Automated Macro Pipeline)
 
@@ -615,6 +703,36 @@ accepts `--json` and `--quiet`. `pre` emits a JSON contract describing the envir
 
 ---
 
+#### `deviate walkthrough pre [--base <branch>] [--branch <branch>]`
+
+* **Source:** `src/deviate/cli/walkthrough.py`
+* **Description:** Gathers git state and governance context for a human-guided
+  architectural walkthrough at HITL Gate 3, complementing `deviate review pre`.
+  Computes the unified diff and file list (via `git diff --name-only`) between
+  the merge-base of `--base` (default: `main`) and `--branch` (default: `HEAD`),
+  resolves governance paths, and collects commit messages for decision traceability.
+  Emits a JSON contract for consumption by the walkthrough skill.
+* **Input Parameters:**
+  * `--base <branch>` (Base branch for merge-base computation; default: `main`)
+  * `--branch <branch>` (Target branch for self-contained walkthrough; default: `HEAD`)
+* **Output Artifacts:** JSON contract with `diff`, `constitution_path`, `prd_path`,
+  `constitution_warning`, `prd_warning`, `base_branch`, `commit_messages`,
+  `changed_files`, `changed_files_count`, `timestamp`.
+* **Token Budget:** Contract is lighter than review's — no per-file AST parsing.
+  The skill reads the raw diff and file list; structured diff is available via
+  `deviate review pre` if deeper analysis is needed.
+
+---
+
+#### `deviate walkthrough post <status>`
+
+* **Source:** `src/deviate/cli/walkthrough.py`
+* **Description:** Placeholder for future walkthrough summary persistence.
+  Currently records the outcome (CLEAN or FLAGGED) with a timestamp.
+* **Input Parameters:**
+  * `status` (Positional: CLEAN or FLAGGED)
+* **Output Artifacts:** JSON contract with `status`, `phase`, `timestamp`.
+
 ### 8. (Removed — Context Sync)
 
 The `deviate context` concept was evaluated and removed. Reasoning:
@@ -769,6 +887,7 @@ and are installed to `.{agent}/commands/<name>.md` per workspace (or `.pi/prompt
 | `/deviate-plan` **← NEW** | Localized Researcher | `specs/{FEATURE_SLUG}/issues/{ISS-NNN}/plan.md` | `deviate plan pre/post` (planned) | 4 steps: read spec-enriched issue, scan current codebase, analyze prior issues, produce plan.md with implementation strategy |
 | `/deviate-tasks` | Technical Lead | `specs/{FEATURE_SLUG}/issues/{ISS-NNN}/tasks.md` | `deviate tasks pre/post` | 6 steps: consume spec-enriched issue + plan.md, decompose into tasks, assign execution modes, encode DAG deps, append terminal E2E task, validate granularity + commit |
 | `/deviate-pr` | Release Engineer | GitHub PR | `deviate pr pre/run` | 3 steps: gather git state, derive PR metadata, create PR via `gh pr create` |
+| `/deviate-walkthrough` | Architectural Walkthrough Guide | (none — conversation only) | `deviate walkthrough pre/post` | 5 steps: gather, sweep, curate, walk (conversational), synthesize |
 
 > **Deprecation Notice:** `/deviate-specify` is deprecated as a standalone step. Shard
 > now produces issues with full spec-level detail (Gherkin AC, user stories, edge cases).
@@ -847,6 +966,7 @@ The architecture defines a model routing strategy in `specs/constitution.md` see
 | `/deviate-shard` | Qwen 3.7+ | Single invocation | One-shot |
 | `/deviate-plan` (new) | V4 Pro | Single invocation | One-shot — fresh localized research per issue |
 | `/deviate-tasks` | V4 Pro | Single invocation (issue-scoped) | 90%+ cache hit after turn 1 when paired with `/deviate-plan` |
+| `/deviate-walkthrough` | V4 Flash | Single invocation | One-shot |
 | `/deviate-adhoc` | V4 Flash | Single invocation | One-shot |
 | EXECUTE / E2E / HOTFIX | V4 Flash | Single invocation | One-shot |