deviatdd 2.23.0__tar.gz → 2.24.0__tar.gz

{deviatdd-2.23.0 → deviatdd-2.24.0}/.gitignore

@@ -10,15 +10,10 @@ __pycache__/
 # Tooling
 .rgr
 .tdd-session.json
-.deviate/session.json
-.opencode/index/
-.codebase-index/
-.opencode/codebase-index.json
+.deviate/
+.opencode/
 node_modules/
 
-.deviate/artifacts/
-.deviate/logs/
-.deviate/review/
 */commands/deviate-*.md
 */prompts/deviate-*.md
 
@@ -35,3 +30,8 @@ node_modules/
 !.env.example
 
 */skills/deviatdd/
+
+*/skills/deviate-*/
+
+# Codebase index (regenerated by open-codebase-index)
+.codebase-index/

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

@@ -8,6 +8,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **`deviate setup --agent pi --agent-export-mode global` now writes to pi's actual global dirs.** Prompt templates go to `~/.pi/agent/prompts/` and the deviatdd skill to `~/.pi/agent/skills/` — pi's `getPromptsDir()` / `getAgentDir()`-relative locations — instead of `~/.pi/prompts/` + `~/.pi/skills/`, which pi only treats as project paths. Local mode (`<workdir>/.pi/prompts`, `<workdir>/.pi/skills`) is unchanged. Pinned by `tests/test_cli/test_setup.py::TestSetupExportModeAndBaseBranch` and the fresh-global-install assertions.
+- **Global installs no longer embed a project's constitution into the prompt.**
+  `install_command(..., export_mode=...)` / `compose_command_body(...,
+  include_constitution=...)` in `src/deviate/core/commands.py` skip tier 0
+  (constitution text) for `--agent-export-mode global`, because the global
+  prompt is project-agnostic and shared across every repo. Project-local
+  installs keep baking `<workdir>/specs/constitution.md` verbatim when the file
+  exists. Global prompts rely on the core block's Constitution Compliance
+  Mandate (invariant #10) to read `specs/constitution.md` at runtime.
+- **Prune classifier is language-agnostic and drops fewer false positives.** The honeycomb classifier in `src/deviate/core/prune.py` now (a) ignores `self._helper(...)` calls — test-own helpers are no longer mistaken for private-state probes, (b) does not drop tests whose spy-assertions mock external boundaries (`subprocess`, `Popen`, agent spawn), (c) recognizes non-Python test declarations (Go `func TestXxx`, Rust `#[test] fn`, JS `describe`/`it`) via a regex fallback alongside the Python AST path, and (d) understands language-native markers (`#[behavioral]`, camelCase `TestBehavioral`) plus Go/JS assertion forms (`t.Fail`, `expect(...).toBe`). Test discovery now globs `*_test`, `*.spec.*`, `*_test.*` in addition to `test_*.py`. The `/deviate-prune` prompt and RED honeycomb-stamp instructions say "markers/annotations/tags" instead of pytest-only marks. Pinned by `tests/test_core/test_prune.py` (new Go/JS fallback test) and existing prune pins.
+- **`deviate setup --agent codex` now pins Luna + high thinking for spawned micro runners.** Fresh Codex setup writes `[models].default = "gpt-5.6-luna"` and `[agent].reasoning_effort = "high"` alongside `backend = "codex"`. Re-running against an existing config upserts those keys only when they are missing or empty — a user-set `[models].default` or `[agent].reasoning_effort` is left alone. Non-Codex setup does not write Luna or a reasoning key. Spawned `codex exec` receives `-c model_reasoning_effort=<value>` from `[agent].reasoning_effort` (official values `minimal|low|medium|high|xhigh`); no repo-wide `.codex/config.toml` is written. Pinned by `tests/test_cli/test_setup.py::TestSetupCodex`, `tests/test_core/test_agent.py::TestCodexBackendRegistration`, and `tests/test_cli/test_micro.py::TestInvokeAgentCodexReasoning`.
+- **ChatGPT Codex is a first-class setup + meso/micro backend.** `--agent codex` (and the interactive prompt) is a valid install target. Setup writes packaged skills to `.agents/skills/deviatdd/SKILL.md` plus one `.agents/skills/<command>/SKILL.md` per slash command (Codex CLI 0.117+ dropped `.codex/prompts`). `[agent].backend = "codex"` is persisted. Dispatch uses `codex exec --sandbox workspace-write --ask-for-approval never` with the existing stdin prompt path and `--model` injection. Transport stays `cli`. Pinned by `tests/test_cli/test_setup.py::TestSetupCodex` and `tests/test_core/test_agent.py::TestCodexBackendRegistration`.
 - **On-demand GitHub Actions Release workflow (`workflow_dispatch`).** A maintainer runs Actions → Release → Run workflow. The job computes the next SemVer from conventional commits since the current `pyproject.toml` version (`feat` → minor, `fix` → patch, `BREAKING CHANGE` / `feat!` / `fix!` → major; chore/docs/test/ci/style/refactor still bump patch), writes `pyproject.toml` + the `deviatdd` version in `uv.lock`, commits `chore(release): version X.Y.Z` on the default branch, tags `vX.Y.Z`, and publishes with `uv build` / `uv publish --trusted-publishing always` (PyPI trusted publishing via GitHub OIDC; `contents: write` + `id-token: write`; no `PYPI_API_TOKEN` and no GitHub secret). Optional inputs: `bump` (`auto` / `patch` / `minor` / `major`) and `dry_run` (print the version; skip commit/tag/publish). Refuses a non-default branch unless `dry_run` is true. Does not rewrite `CHANGELOG.md` (stays `[Unreleased]`). Operator adds a pending PyPI trusted publisher for `wernerbisschoff/deviatdd` workflow `release.yml` (no environment). Local fallback remains `mise run publish`. Pinned by `tests/test_release/test_next_version.py`.
 - **COMPLETED `tasks.jsonl` rows now persist runner-validated JUDGE evidence (GH-84).** After the #65 mechanical gate accepts a TDD completion path (`skip_refactor` / bare `COMPLIANCE_PASS` / post-REFACTOR complete / adjudicated already-exists), `_append_status_transition(..., "COMPLETED")` copies `HandoverManifest.evidence` (`ac`, `test_path`, `test_quote`, `impl_path`, `impl_quote`) onto an optional `TaskRecord.evidence` bundle and stamps `red` (`session.red_commit_sha`) plus `green`/`head` (`HEAD` at the write). TDD complete fail-closes when the plan contract has `AC-PLAN-NNN` tokens and the bundle is missing or does not cover them (`evaluate_judge_evidence`, no new matcher). EXECUTE / IMMEDIATE / DIRECT stay ungated; enabling/infra plans with no AC tokens may complete with empty evidence. `deviate inspect tasks show` prints the field when present. Session files are not the proof store. Pinned by `tests/test_micro/test_completed_evidence.py`, `tests/test_state/test_ledger.py`, and `tests/test_cli/test_inspect.py`.
 - **`deviate micro run --review` pauses before each phase commit (GH-101).** After the agent finishes a phase and tests/lint have run, `--review` (and `--all --review`) halt before `_commit_phase` / `_commit_phase_with_recovery` (`git add -A`), print `REVIEW_PAUSE <phase> <task_id>`, leave the worktree dirty for herdr/hunk, and wait for TTY confirmation (`Enter` / yes). Then the runner commits as today and continues. Pause applies to RED, GREEN, REFACTOR, and EXECUTE — not JUDGE feedback commits. RED is still committed before GREEN so `session.red_commit_sha` remains available for JUDGE `revert_to_red`. Non-TTY / `--json` / missing stdin fail closed with `REVIEW_REQUIRES_TTY` and never auto-commit past the flag. Off by default; no config key. The pause is one helper (`_maybe_review_pause`) in front of `_commit_phase`, not a copy in each phase. Pinned by `tests/test_micro/test_review_pause.py`.
@@ -29,8 +41,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`deviate specify --local` claims an issue without pushing to the remote.** When `--local` is set, `_try_claim_issue` skips the `branch_exists_on_remote` check and the `git push` step, so the worktree is created, the ledger row is written, and the claim commit is recorded locally only. If the local branch `feat/<epic>/<slug>` already exists, the command short-circuits with `ALREADY_CLAIMED_LOCAL` and reuses the existing worktree, treating branch presence as the claim signal without rewriting the ledger. NOTE: this semantic can false-positive on a manual `git checkout -b feat/<epic>/<slug>` that pre-dated any claim — there is no opt-in to disable it for the no-remote workflow, so prefer `deviate specify <id>` (the default, which checks remote first) when operating against a shared origin. The new option lives at `src/deviate/cli/meso.py::_try_claim_issue(..., local=...)` and the `specify` Typer command forwards it through `_specify_pre`. Pinned by `tests/test_meso/test_specify.py::TestSpecifyLocalFlag` (2 tests: branch-exists short-circuit, kwargs forwarded) and `tests/test_cli/test_meso.py::TestSpecifyLocalFlag` (4 tests: remote check skipped, push skipped, short-circuit dict shape, branch-exists short-circuit).
 - **`deviate flows sync` — sole owner of `specs/_product/flows.jsonl` creation.** New top-level `flows` Typer group exposes a single `sync` subcommand that parses `specs/_product/flows/index.md` and appends one ``FlowRecord`` identity row plus ``FLOW_DISCOVERED`` and ``FLOW_DOCUMENTED`` events per flow. Re-running on a populated ledger is a no-op (compound-key idempotency on the underlying append helpers). Exits non-zero with ``FLOWS_INDEX_MISSING`` on stderr when the canonical index is absent, and ``FLOWS_INDEX_EMPTY`` when the index parses to zero rows — surfaces authoring defects instead of silently committing a half-baked catalog. New public service `seed_flow_ledger(flows_index, ledger_path)` in `src/deviate/state/ledger.py` plus `FlowIndexEmptyError` for the empty-index contract. `deviate explore post` no longer seeds identity or documentation events; it only renders the coverage report. ``flows.jsonl`` never receives ``FLOW_REFERENCED_BY_ISSUE`` events — the referenced-by relationship is derived read-only from ``specs/issues.jsonl::flow_refs`` at coverage time.
 - **`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` defaults to `true` (absent file or absent key still push). `deviate setup --no-claim-remote` writes `claim_remote = false` without dropping `[models]`, `timeout_seconds`, or `[agent]`. Fresh setup without the flag writes `true`. 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` now 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` (Atomic Concurrency Protocol: push-as-lock is the default, not mandatory). 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`.
+- **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
+- **`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 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.
+- **`deviate setup` default install is execution layers only.** Product is one optional pack (`deviate-flows` + `deviate-architecture` + `deviate-release`, kept together), not a default layer. Bare setup / `--packs none` / TTY default `none` write `macro` + `meso` + `micro` (including `/deviate-init`) plus the shared `deviatdd` skill. The TTY optional-pack selector lists `none`, `all-optional`, then `product` first among named packs, then the existing individuals (`merge`, `pr`, `review`, `walkthrough`, `html`, `hotfix`, `triage`, `prune`, `e2e`). `--packs product` writes all three product commands; `--packs all-optional` includes `product`. Pinned by `tests/test_cli/test_setup.py::TestSetupPacks` and `tests/test_core/test_commands.py::TestCommandPacks`.
+- **`deviate setup` now installs commands and the `deviatdd` skill only to the targeted agent, and auto-detects installed agents when `--agent` is omitted.** `--agent <name>` writes command and skill files only under that agent's directory and fails closed with `AGENT_NOT_INSTALLED` when the named agent is declared but not installed; omitting `--agent` targets exactly the directories `detect_agents` reports as present (`.claude/`, `.opencode/`, `.factory/`, `.pi/`, `.omp/`), instead of the previous install-to-all active-agents dispatch. The `.deviate/` directory is now git-ignored by default through `_ensure_root_gitignore` (new `.deviate/` entry) and the `.deviate/.gitignore`/`.gitignore` provisioning kept intact for existing tracked history (AO-030-01 Boundary). The `[agent].timeout` config field is removed: agent-process and test-command deadlines both resolve from the single consolidated `DeviateConfig.timeout_seconds` (`resolve_agent_deadline`, default 1800s), while the Graphite config surface is fully removed. The `[models]` phase→model resolution order (phase key → `default` → backend-native) is unchanged. Pinned by `tests/test_state/test_config.py`, `tests/test_cli/test_setup.py`, and `tests/test_integration/test_skill_installation.py`.
+- **Push-as-lock is opt-in.** Absent `claim_remote` key, absent `.deviate/config.toml`, and fresh `deviate setup` all mean local claims only (`claim_remote = false`). Fresh setup writes `claim_remote = false`. `deviate setup --claim-remote` writes `true`; `--no-claim-remote` still writes `false`. The TTY prompt “Push claim branches to the remote as a lock” defaults to no. Existing `claim_remote = true` configs keep pushing. `--local` still forces local; effective local remains `--local` OR `claim_remote = false`. Worktrees and local claim commits are unchanged. Specs: `specs/DeviaTDD-api.md`, `specs/DeviaTDD-architecture.md`. Pinned by `tests/test_state/test_config.py`, `tests/test_cli/test_setup.py`, `tests/test_cli/test_init.py`, `tests/test_cli/test_meso.py`, `tests/test_meso/test_specify.py`, `tests/test_meso/test_meso_orchestration.py`, and `tests/test_cli/test_top_level_run.py`.
+- **Micro execution profiles are only `full` and `fast`.** `full` runs JUDGE + REFACTOR; `fast` skips both. `--no-judge` / `--no-refactor` remain composable overrides. The old `secure` name is not a public profile and is not a security mode — it stays an undocumented internal alias that keeps JUDGE and skips REFACTOR (`profile = "secure"` / `--profile secure`). Legacy `profile = "default"` still coerces to `full`. `TaskRecord.security_profile` is unchanged. Pinned by `tests/test_core/test_profile.py` and `tests/test_state/test_config.py`.
+- **New-user path is `deviate setup` then `/deviate-init`.** README Quickstart and the Workflow Bootstrap rows no longer claim that setup scaffolds `specs/constitution.md` "in one shot". Setup writes `.deviate/`, persists the agent, and installs default packs (including `deviate-init`) plus the shared `deviatdd` skill. `/deviate-init` (Codex: the `deviate-init` skill) scaffolds `specs/constitution.md`, `mise.toml`, and `specs/issues.jsonl`, skipping files already present. Successful `deviate setup` prints a next-step hint to run `/deviate-init` (no-op if the repo is already scaffolded). Pinned by `tests/test_cli/test_setup.py::TestSetupNextStepHint` and `::TestReadmeNewUserPath`.
+- **`deviate setup` is pack-aware and writes a production-clean `config.toml`.** Omitted `--packs` installs the default layer set (macro + meso + micro plus the shared `deviatdd` skill) and leaves optional packs (`product`, `merge`, `pr`, `review`, `walkthrough`, `html`, `hotfix`, `triage`, `prune`, `e2e`) uninstalled. `--packs none|all-optional|pr,review` (or a TTY prompt) selects optional packs. Generated config always keeps `base_branch` and `claim_remote`; `profile` is now `full`/`fast` (default `full`) and is the `deviate micro run` default when `--profile` is omitted (legacy `profile = "default"` coerces to `full`; legacy `profile = "secure"` remains an undocumented alias that keeps JUDGE and skips REFACTOR). `--libref` is the only libref opt-in — without it there is no `use_libref` key and no libref mention in generated config, governance seeds, or installed command/skill bodies. `[agent]` persists the chosen backend (`codex` when Codex is picked) and writes `transport` only for `pi`/`omp`; `pi_rpc` is never written. Codex Luna + high-reasoning if-empty defaults are unchanged. Pinned by `tests/test_cli/test_setup.py`, `tests/test_core/test_commands.py`, and `tests/test_state/test_config.py`.
+- **The `deviatdd` skill accepts an optional `review` argument that pauses after each successful task.** Default invoke (no argument) still auto-continues `deviate micro run` until `NO_PENDING_TASKS`. When `$ARGUMENTS` contains `review` (or `/deviatdd review` / "deviatdd with review"), the agent stops after each exit 0, shows the task id and the commits just made, and waits for the human before the next bare `deviate micro run`. Does not pass `--review` or `--all` to the runner. Prompt-only change to `src/deviate/prompts/skills/deviatdd/SKILL.md`.
+- **`/deviate-prune` is a manual honeycomb test-thinning surface.** Prefer pytest marks and name tags (`spy` / `impl` drop, `behavioral` / `ac` keep). Untagged tests are classified from the body (drop internal spies/mocks/private state; keep public input-to-output / AC) and must not auto-keep. RED stamps `@pytest.mark.behavioral` | `@pytest.mark.spy` | `@pytest.mark.impl` on each new test (most are behavioral). Prune is manual invoke only — not hooked into micro COMPLETED, `--all`, or the `deviatdd` skill success loop. `apply_prune` / READY never unlinks `plan.md`, `tasks.md`, `explore.md`, `prd.md`, issue md, leftover cycle markdown, or JSONL ledgers. Compact / squash / rewrite is rejected. Thin `deviate prune pre` / `post` CLI is registered. One issue per invocation. Pinned by `tests/test_core/test_prune.py` and `tests/test_cli/test_prune.py`.
 - **The `deviatdd` skill checks for an existing OPEN GitHub issue before filing a harness-bug issue.** The "Filing deviatdd issues" section now runs `gh issue list --repo wernerbisschoff/deviatdd --state open --search` first; when an open issue already matches the same harness failure, it directs commenting the new evidence/task context onto that issue (`gh issue comment`) instead of `gh issue create`, and only creates a new issue when no match exists. Prompt-only change to the packaged skill (`src/deviate/prompts/skills/deviatdd/SKILL.md`), re-installed to all agent skill dirs.
 - **`deviate refactor pre` now scopes `files_to_refactor` to the RED+GREEN production set (GH-98).** The command no longer glob()s every `src/**/*.py` or discards `_resolve_task_context`. It lists production files from `HEAD~2..HEAD`, falling back to the task `Files:` list minus tests when that git range is empty or unavailable. Test files are never included. The JSON contract now emits the documented handover fields (`status`, `task_id`, `task_title`, `task_type`, `test_command`, `lint_command`, `spec_dir`, `verification`, `repo_root`, `git_branch`, `timestamp`) alongside `files_to_refactor`. Auto `_build_auto_prompt("refactor")` injects the same scoped list and keeps the `git log -2` / `git diff HEAD~2..HEAD` inspect step. Pinned by `tests/test_micro/test_refactor.py`.
 - **GREEN / REFACTOR / review prompts fold smallest-change into existing lines** (reuse stdlib or an already-installed dep; in-place refactor; Opportunities do not extract helpers). Prompt-only. Pinned by `tests/test_meso/test_auto_prompt_templates.py::TestSmallestChangeFoldedIntoExistingPrompts`.
@@ -55,6 +80,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
+- **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`.
 - **JUDGE prompt injection now uses the Judge-Feedback-stripped task card (GH-118).** `_build_auto_prompt("judge")` still reads the raw card via `_task_card_text`, then applies the same `_strip_judge_feedback` pass that `resolve_task_ac_tokens` already used for token resolution (#89). Prior-round `**Judge Feedback**` bullets and their continuation lines (including false ownership claims such as "AC-PLAN-003 belongs to a later task") no longer appear in `<task_card>`. Token resolution, `_append_judge_feedback`, and the COMPLETED evidence gate are unchanged. Specs: `specs/DeviaTDD-api.md`, `specs/DeviaTDD-architecture.md`. Pinned by `tests/test_micro/test_judge.py::TestJudgePromptStripsJudgeFeedback`.
 - **Ledger appenders no longer concatenate a new JSONL record onto a last line that lacks a trailing newline (GH-117).** `_append_record` and `_append_with_compound_key` insert a leading `\n` when the file is non-empty and does not already end in a newline, so `_read_ledger` cannot skip a fused BACKLOG+SPECIFIED line. `claim_issue` now writes through `append_issue_transition` instead of a raw `"a"` append. Pinned by `tests/test_state/test_ledger.py` and `tests/test_core/test_issues.py`.
 - **JUDGE handover parse now recovers unescaped `"` inside evidence quote fields (GH-116).** `AgentBackend.parse_output` retries `yaml.safe_load` after rewriting broken `quote` / `test_quote` / `impl_quote` double-quoted scalars as `|` block scalars, so citations such as `assert "YAGNI" in text` and `== ["AC-PLAN-002"]` no longer raise `MalformedHandoverManifestError`. Well-formed YAML is unchanged. The auto judge prompt also prefers `|` block scalars when a quote contains `"`. Pinned by `tests/test_core/test_agent.py`.

{deviatdd-2.23.0 → deviatdd-2.24.0}/CLAUDE.md

@@ -92,7 +92,3 @@ Prefer `libref query <lib> "<topic>"` over web fetching. Workflow: `libref list`
 ## 📝 Prompt Edit Discipline
 
 Edit skill/prompt templates in `src/deviate/prompts/` only. `~/.config/opencode/skills/` is a read-only install mirror.
-
-## 🌳 Graphite (when `graphite = true` in `.deviate/config.toml`)
-
-`gt create -am "msg"` (or `-m` if tree clean) → `gt submit --stack` → `gt sync`. Never mix `git checkout -b` with `gt`, never `gh pr create` when Graphite is on.

{deviatdd-2.23.0 → deviatdd-2.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: deviatdd
-Version: 2.23.0
+Version: 2.24.0
 Summary: DeviaTDD CLI — agent orchestration framework
 Project-URL: Homepage, https://github.com/wernerbisschoff/deviatdd
 Project-URL: Repository, https://github.com/wernerbisschoff/deviatdd
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 # DeviaTDD
 
-> **An agent-orchestration framework that runs your entire TDD loop — explore, spec, red, green, refactor — with three mandatory human-in-the-loop gates.**
+> **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.
 
@@ -54,7 +54,7 @@ Most AI coding agents stop at "write code that passes." DeviaTDD goes further
 
 | Without DeviaTDD | With DeviaTDD |
 |------------------|---------------|
-| Agent writes code, you review after | Three mandatory human gates: design, contract, merge |
+| 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 |
@@ -72,16 +72,19 @@ Most AI coding agents stop at "write code that passes." DeviaTDD goes further
 uv tool install deviatdd
 deviate --version                # confirm install
 
-# Bootstrap a new project + install slash commands into your agent of
-# choice. Does it all in one shot: scaffolds .deviate/, specs/constitution.md,
-# governance blocks, and installs /deviate-* slash commands for every
-# supported agent. The --agent flag picks the default backend persisted
-# to .deviate/config.toml (slash commands themselves are installed to all
-# supported agent directories regardless).
-deviate setup --agent claude     # or: opencode | pi | droid | factory | omp
+# Step 1 — bootstrap DeviaTDD into this repo.
+# Writes .deviate/, persists the agent, installs default packs
+# (including deviate-init) and the shared deviatdd skill for the
+# selected agent only. Does not write specs/constitution.md,
+# mise.toml, or specs/issues.jsonl — that is /deviate-init.
+# A TTY session prompts for the agent; --agent skips the prompt
+# (`droid` writes `.factory/`; `codex` writes `.agents/skills/`).
+deviate setup --agent claude     # or: opencode | pi | droid | factory | omp | codex
 ```
 
-Once setup is done, drive the entire lifecycle from inside your agent. Each phase emits a single artifact, commits it, and (at the two gates) pauses for human review.
+Once setup finishes, open your agent and run **`/deviate-init` as the first prompt**. That scaffolds `specs/constitution.md`, `mise.toml`, and `specs/issues.jsonl`, skipping anything already present. Codex uses the same prompt, installed as the `deviate-init` skill.
+
+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):*
 
@@ -104,7 +107,7 @@ Once setup is done, drive the entire lifecycle from inside your agent. Each phas
 /deviate-adhoc "Add a /healthz endpoint"   # condenses explore+research+prd+shard into one issue
 ```
 
-**Meso — claim the issue and enter its worktree.** Meso slash commands run inside the per-issue worktree; claim first, then `cd` in:
+**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):
@@ -113,6 +116,9 @@ deviate specify                            # auto-claim the next unblocked BACKL
 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:
@@ -140,11 +146,12 @@ cd $(deviate specify ISS-001-007 2>&1 | grep '^WORKTREE' | awk '{print $2}')
 /deviate-execute  T002                   # skips the TDD cycle; still has its own JUDGE pass
 ```
 
-**Release** — close the loop:
+**Release** — close the loop. `/deviate-pr`, `/deviate-review`, and `/deviate-walkthrough` are **optional packs** (not in default setup on current main):
 
 ```
 /deviate-pr       T001                   # conventional-commit PR; merge appends COMPLETED
-/deviate-review                          # ← Gate 3: final PR scan; merge or request changes
+/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
@@ -228,7 +235,8 @@ style Ex fill:#f5e1e1
 
 | Phase | Slash command | Artifact committed | What the human reviews / decides |
 |-------|---------------|--------------------|----------------------------------|
-| **Bootstrap** | `deviate setup --agent <name>` | `.deviate/config.toml`, `specs/constitution.md`, governance blocks, installed `/deviate-*` slash commands | Sanity-check the constitution and the agent skills list; commit. |
+| **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. TTY always shows the agent selector (existing backend is the default highlight) and a checkbox list of optional packs (`product` first; Space toggles, Enter confirms; default none). |
+| **Bootstrap · Init** | `/deviate-init` | `specs/constitution.md`, `mise.toml`, `specs/issues.jsonl` (skips files already present) | **First prompt after setup.** Codex: the `deviate-init` skill. No-op if the repo is already scaffolded. |
 | **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. |
@@ -236,7 +244,7 @@ style Ex fill:#f5e1e1
 | **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>/`, a claim entry appended to `specs/issues.jsonl`, and the branch pushed to remote | 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. |
+| **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`. |
@@ -246,24 +254,43 @@ style Ex fill:#f5e1e1
 | **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. |
+| **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. Auto-apply of CRITICAL+SUGGESTION is old PyPI 2.23.1 — not current main. |
+| **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 on current main (#134) 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`. PyPI 2.23.1 still installs all slash files — that is not current main.
 
-Operational tools (no gate, no commit): `/deviate-triage`, `/deviate-constitution`, `/deviate-hotfix`, `/deviate-prune`.
+| Phase | Does | Commits | Debug a fail |
+|-------|------|---------|--------------|
+| **setup** | Writes `.deviate/`, persists one agent, installs default packs + `deviatdd`. `claim_remote` defaults **false**. | 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
 
-DeviaTDD's phase structure is not arbitrary. Each phase exists because the alternative — an agent that skips it — produces a documented failure mode. The rationale below is split into five parts: why the four layers exist, why each Product / Macro / Meso phase exists, why the three non-bypassable human gates exist, why the append-only ledgers exist, and why the TDD micro-loop is `Red → Green → Judge/Train → Refactor`. Direct article citations appear inline in italics; consolidated URLs are listed under [References](#references) below.
+DeviaTDD's phase structure is not arbitrary. Each phase exists because the alternative — an agent that skips it — produces a documented failure mode. The rationale below is split into five parts: why the four layers exist, why each Product / Macro / Meso phase exists, why the two hard human gates exist (design/contract review and merge; shard is soft), why the append-only ledgers exist, and why the TDD micro-loop is `Red → Green → Judge/Train → Refactor`. Direct article citations appear inline in italics; consolidated URLs are listed under [References](#references) below.
 
 ### Why the four layers
 
-- **Each layer matches a different model strength and a different cost profile.** Spec authoring, issue decomposition, and isolated judgement are high-judgment, low-frequency tasks best suited to a strong model. Test writing, implementation, and refactor are high-frequency, low-judgment tasks that a cheap model can perform with the right context. Splitting them into layers routes each turn to the appropriate model — a structural implementation of cost-optimal cascade routing *(UCCI; RoBatch; TDAD)*.
-- **Layering converts a monolithic chat into a chain of accountable artifacts.** Each phase commits a single artifact (an exploration note, a design doc, an issue file, a test, a commit). A chain of small, committed artifacts is auditable, recoverable, and parallelizable; a single long conversation is none of those *(Agile-V; SDD; Spec Kit)*.
+- **Each layer matches a different model strength and a different cost profile.** Spec authoring, issue decomposition, and isolated judgement are high-judgment, low-frequency tasks best suited to a strong model. Test writing, implementation, and refactor are high-frequency, low-judgment tasks that a cheap model can perform with the right context. Splitting them into layers routes each turn to the appropriate model. *_(UCCI's 31% cost cut is a NER cascade, not coding-agent layer routing; RoBatch is batch prompting for data-management ICL. Neither paper is evidence that Product/Macro/Meso/Micro exist.)_*
+- **Layering converts a monolithic chat into a chain of accountable artifacts.** Each phase commits a single artifact (an exploration note, a design doc, an issue file, a test, a commit). A chain of small, committed artifacts is auditable, recoverable, and parallelizable; a single long conversation is none of those *(SDD stages Specify → Plan → Implement → Validate; Spec Kit stages Specify/Plan/Tasks/Implement. Agile-V has two layers — Agile-V lifecycle + SCOPE-V task loop — and argues for a reviewed brief rather than a long chat. None of these papers define Product/Macro/Meso/Micro)*.
 - **The Product layer is optional because most repos only ship one feature stream at a time.** A team maintaining ten products needs cross-product framing; a team shipping one web app does not. Making the Product layer optional means DeviaTDD does not impose ceremony on teams that do not need it. *_(Design proposal — closest supporting evidence is Agile-V's R0–R3 risk-adaptive framing, which is about gate strictness, not layer optionality.)_*
-- **The Macro / Meso / Micro split separates *what to build* from *how to build it* from *how to verify it*.** Macro is intent. Meso is structure. Micro is verification. Conflating any two of these in a single prompt is a documented source of agent failure — the model loses the discipline of one role while playing another *(Survey; SDD)*.
-- **Escalation between layers is risk-gated, not always-on.** The strong model intervenes as judge or verifier when the repair budget exhausts or when the change touches protected modules. Routine work stays in the cheap layer; high-risk work escalates automatically *(Agile-V; TDDev; UCCI)*.
+- **The Macro / Meso / Micro split separates *what to build* from *how to build it* from *how to verify it*.** Macro is intent. Meso is structure. Micro is verification. SDD separates *what* from *how* at the feature level (Specify vs Plan); Spec Kit uses the same feature stages. That is not a documented finding that conflating what/how/verify in one prompt is an agent failure — the Survey is a neural-vs-symbolic architecture review and does not make that claim.
+- **Escalation between layers is risk-gated, not always-on.** The strong model intervenes as judge or verifier when the repair budget exhausts or when the change touches protected modules. Routine work stays in the cheap layer; high-risk work escalates automatically *(Agile-V — R0–R3 risk-adaptive acceptance. TDDev studies protocol–model fit for web-app TDD, not layer escalation; UCCI is NER cascade routing.)*
 
 ### Why the Product layer phases exist
 
@@ -274,41 +301,40 @@ DeviaTDD's phase structure is not arbitrary. Each phase exists because the alter
 
 ### Why the Macro layer phases exist
 
-- **The Macro layer is the only place where a business goal is decomposed into spec-enriched issues at the right granularity.** Without a dedicated decomposition layer, the agent either ships the goal as one monolithic change (too large to review) or as ad-hoc task lists (too small to be independently testable). The Macro layer is where the granularity decision is made *(Agile-V; SDD)*.
-- **Splitting Explore and Research is what lets a cheap model do the cheap work and a strong model do the strong work.** Explore is a factual codebase scan; Research is an architectural reasoning task. A combined phase would either over-pay for trivial scans or under-pay for critical design decisions. The split routes each turn to the appropriate model and gives the human a cheaper artifact to review at the cheap stage *(Spec Kit)*.
-- **Keeping Explore a *what exists* artifact, not a *what to do* artifact, is what lets the research phase build on it without inheriting the scan's biases.** A factual scan is the only input a research phase can build on without smuggling in design recommendations. Conflated "scan and recommend" phases lock the research phase into a direction before the human has reviewed anything *(Spec Kit; parallel: Agile-V)*.
-- **Splitting the PRD, the design, and the data-model into three artifacts is what lets each be reviewed by a different lens and revised on a different cadence.** The PRD is *what* the system must do (requirements); the design is *how* (architecture); the data-model is *what shape the information takes* (entities, relations). Conflated artifacts force joint review and weaken every review *(SDD; Agile-V)*.
-- **Testable acceptance criteria are the requirement for a requirement to enter the PRD.** A requirement without criteria is a wish; a PRD full of wishes cannot be sharded because there is nothing for the issues to test against. The criterion test is what turns a wishlist into a PRD *(SDD — "passing spec tests only guarantee the code matches the spec"; Definitive SDD — 3–10× higher first-pass success rate via structured specs; Acceptance Test Gen — LLM-generated acceptance tests are usable in production at 60% as-generated, 92% after fixes; LLM BDD)*.
-- **Decomposing a feature into vertical slices, not horizontal layers, is what makes each issue independently shippable and Gate-2-reviewable.** A vertical slice is a complete, testable behavior end-to-end; a horizontal layer is a file or module. Vertical slices can be reviewed for missing behavior; horizontal layers hide integration risk until merge *(TDFlow; TDDev)*.
-- **Decomposing a feature into vertical slices, not horizontal layers, is what makes each issue independently shippable.** A vertical slice is a complete, testable behavior end-to-end; a horizontal layer is a file or module. Vertical slices can be reviewed for missing behavior; horizontal layers hide integration risk until merge *(TDFlow; TDDev)*.
+- **The Macro layer is the only place where a business goal is decomposed into spec-enriched issues at the right granularity.** Without a dedicated decomposition layer, the agent either ships the goal as one monolithic change (too large to review) or as ad-hoc task lists (too small to be independently testable). The Macro layer is where the granularity decision is made *(SDD decomposes a feature through Specify → Plan → Implement → Validate; Spec Kit through Specify/Plan/Tasks/Implement — neither is Product/Macro/Meso/Micro; Agile-V has two layers — lifecycle + SCOPE-V)*.
+- **Splitting Explore and Research is what lets a cheap model do the cheap work and a strong model do the strong work.** Explore is a factual codebase scan; Research is an architectural reasoning task. A combined phase would either over-pay for trivial scans or under-pay for critical design decisions. The split routes each turn to the appropriate model and gives the human a cheaper artifact to review at the cheap stage. *(Spec Kit's discovery/validation hooks ground Specify/Plan/Tasks/Implement in repository evidence; they are not an Explore/Research cheap-vs-strong model split. Spec Kit plan-review is optional; a 40-minute arm skips intermediate artifacts.)*
+- **Keeping Explore a *what exists* artifact, not a *what to do* artifact, is what lets the research phase build on it without inheriting the scan's biases.** A factual scan is the only input a research phase can build on without smuggling in design recommendations. Conflated "scan and recommend" phases lock the research phase into a direction before the human has reviewed anything. *(Spec Kit discovery hooks collect repository evidence before a stage; they do not name an Explore-as-inventory phase. Agile-V treats conversation as discovery and structured artifacts as the implementation contract.)*
+- **Splitting the PRD, the design, and the data-model into three artifacts is what lets each be reviewed by a different lens and revised on a different cadence.** The PRD is *what* the system must do (requirements); the design is *how* (architecture); the data-model is *what shape the information takes* (entities, relations). Conflated artifacts force joint review and weaken every review *(SDD separates Specify (what) from Plan (how) at the feature level; Agile-V's two layers are lifecycle + SCOPE-V, not PRD/design/data-model)*.
+- **Testable acceptance criteria are the requirement for a requirement to enter the PRD.** A requirement without criteria is a wish; a PRD full of wishes cannot be sharded because there is nothing for the issues to test against. The criterion test is what turns a wishlist into a PRD *(SDD — "passing spec tests only guarantee the code matches the spec"; BCMS vendor blog — "~3–10× higher first-pass success rate … according to early adopter reports," not the SDD paper; Acceptance Test Gen — LLM-generated acceptance tests are usable in production at 60% as-generated, 92% after fixes; LLM BDD)*.
+- **Decomposing a feature into vertical slices, not horizontal layers, is what makes each issue independently shippable.** A vertical slice is a complete, testable behavior end-to-end; a horizontal layer is a file or module. Vertical slices can be reviewed for missing behavior; horizontal layers hide integration risk until merge. *_(TDFlow and TDDev do not use the word "vertical." TDFlow is forced-decoupled sub-agents on SWE-bench given human-written tests; TDDev compares TDD protocols by model generation style. The vertical-slice wording is DeviaTDD's.)_*
 - **A complexity gate (low / medium → proceed, high → reject) is what makes Adhoc safe to expose as a shortcut.** Without the gate, "adhoc" becomes a workaround for skipping ceremony on work that needs the full Macro chain. The gate is the structural mechanism that prevents the shortcut from being misused. *_(Adaptive-enforcement concept is parallel to TDDev's protocol-model fit and TDD Governance's N=3 repair cap; the specific "low/medium → proceed, high → reject" classifier is DeviaTDD-original.)_*
 
 ### Why the Meso layer phases exist
 
-- **The Meso layer is the only place where a spec-enriched issue is decomposed into TDD-executable tasks at the right granularity.** A spec is too coarse for a single TDD cycle (15–60 minutes); a task list is too fine for a human to review coherently. The Meso layer is where the granularity decision is made *(TDAID)*.
-- **Re-running Plan per issue is what keeps the "what exists now" context fresh within a sprint.** Epic-level Explore becomes stale within days — by the time the fifth issue of a feature is being planned, the codebase has changed and prior issues have shipped. Per-issue Plan reads what prior issues implemented via the issues ledger, so the context reflects the current state, not the state at the start of the epic. *_(Parallel: Mise en Place's per-task fresh-context principle and Runtime Decomp's runtime-branching. The specific "per-issue Plan reads prior issues via the issues ledger" pattern is DeviaTDD-original.)_*
-- **Human review of decomposition and machine execution of decomposition require different formats and must be separate files.** `tasks.md` is the only surface a human can read, amend, and approve task decomposition against; `tasks.jsonl` is the only surface a CLI can parse deterministically and replay across parallel branches. Combining them forces one format to compromise on both readers *(TDAD — `test_map.txt` vs `SKILL.md` separation; TDFlow — diffs computed against the same baseline, machine-parseable and replayable across parallel branches)*.
-- **The 4–8 tasks-per-issue target matches the granularity at which a single TDD cycle can complete in 15–60 minutes — outside that range, the cycle becomes either fragmented or bloated.** More tasks force micro-decomposition that fragments the acceptance criteria; fewer tasks hide integration risk and balloon the cycle time past human-tolerable. *_(The 15–60 min cycle target is supported by TDAID; the specific 4–8 count is DeviaTDD-original.)_*
-- **Explicit DAG `blocked_by` dependencies are what make the parallel work graph visible to both the CLI and the human reviewer.** A flat list of tasks with implicit order is invisible to a parallelizing CLI and uninspectable to a human looking for the critical path. The DAG is the only structure that supports parallel-execution scheduling and critical-path reasoning *(Runtime Decomp — 80.5% lower retry cost vs. static decomposition; parallel: TDFlow)*.
+- **The Meso layer is the only place where a spec-enriched issue is decomposed into TDD-executable tasks at the right granularity.** A spec is too coarse for a single TDD cycle; a task list is too fine for a human to review coherently. The Meso layer is where the granularity decision is made. *(TDAID describes Plan → Red → Green → Refactor → Validate. It does not give a 15–60 minute cycle time.)*
+- **Re-running Plan per issue is what keeps the "what exists now" context fresh within a sprint.** Epic-level Explore becomes stale within days — by the time the fifth issue of a feature is being planned, the codebase has changed and prior issues have shipped. Per-issue Plan reads what prior issues implemented via the issues ledger, so the context reflects the current state, not the state at the start of the epic. *_(Parallel: Mise en Place's three preparation phases — contextual grounding, collaborative specification, task decomposition — and Runtime Decomp's runtime branching. Mise en Place does not name a "fresh-context per task" phase. The specific "per-issue Plan reads prior issues via the issues ledger" pattern is DeviaTDD-original.)_*
+- **Human review of decomposition and machine execution of decomposition require different formats and must be separate files.** `tasks.md` is the only surface a human can read, amend, and approve task decomposition against; `tasks.jsonl` is the only surface a CLI can parse deterministically and replay across parallel branches. Combining them forces one format to compromise on both readers *(TDAD — `test_map.txt` vs `SKILL.md` separation: shrinking `SKILL.md` 107 → 20 lines raised resolution 12% → 50%; the 70% regression cut (6.08% → 1.82%) is an impact-map / `test_map.txt` result, not a red-first result)*.
+- **The 4–8 tasks-per-issue target is the granularity DeviaTDD uses so each task stays reviewable and independently testable — outside that range, decomposition becomes either fragmented or bloated.** More tasks force micro-decomposition that fragments the acceptance criteria; fewer tasks hide integration risk. *_(The specific 4–8 count is DeviaTDD-original. TDAID does not state a 15–60 minute cycle.)_*
+- **Explicit DAG `blocked_by` dependencies are what make the parallel work graph visible to both the CLI and the human reviewer.** A flat list of tasks with implicit order is invisible to a parallelizing CLI and uninspectable to a human looking for the critical path. The DAG is the only structure that supports parallel-execution scheduling and critical-path reasoning *(Runtime Decomp — on the Kubernetes RCA workload (N=10, simulated failure), static decomposition's retry cost exceeded monolithic by 80.5%; runtime-branched vs monolithic was 51.7% lower retry cost and vs static 73.2%. The 80.5% figure is static *worse than monolithic*, not a win for runtime vs static)*.
 - **Treating the GitHub PR as a structural merge boundary, not a code-formatting step, is what gives reviewers a single artifact to review (title, body, diff, review surface).** A list of commits is a history; a PR is the unit of *what we are about to merge* *(Agile-V — SCOPE-V's verify step at "before / during / before-merge / after-deployment", treating the merge boundary as a discrete verification point)*.
 - **Gate 3 (final PR review) is the only audit over the full atomic git history of a feature.** Per-task review sees a slice; Gate 3 sees the whole. A final human audit catches the long-tail issues — integration regressions, doc drift, scope creep — that escaped per-task validation *(extension of Agile-V's verify-step pattern)*.
 
 ### Why two non-bypassable human gates
 
-- **Spec errors are the most expensive to fix downstream.** A bug in a contract caught at the post-shard review saves the plan, the tasks, and every TDD cycle that would have implemented the bug. The same bug caught after merge costs the bug report, the rollback, the post-mortem, and the customer trust. Task decomposition is cheap to regenerate; cascades of implemented tasks are not *(Agile-V — SCOPE-V's evidence-based acceptance; SDD — 3–10× first-pass success via structured specs)*.
-- **An LLM cannot self-verify its own output.** Every frontier model is a stochastic generator with zero internal semantic verification capability — the tool is irrelevant, the process is determinative. The same agent that produces a plausible design or plausible code will produce a plausible-looking review of them. A human gate at design and merge is the only verification mechanism with the necessary independence *(IACDM — "verification gap"; PRIME — Executor/Verifier asymmetry; State Contamination — memory laundering preserves adversarial influence below classifier threshold)*.
+- **Spec errors are the most expensive to fix downstream.** A bug in a contract caught at the post-shard review saves the plan, the tasks, and every TDD cycle that would have implemented the bug. The same bug caught after merge costs the bug report, the rollback, the post-mortem, and the customer trust. Task decomposition is cheap to regenerate; cascades of implemented tasks are not *(Agile-V — SCOPE-V's evidence-based acceptance. The 3–10× first-pass figure is a BCMS early-adopter report, not a finding in the SDD paper)*.
+- **An LLM cannot self-verify its own output.** Every frontier model is a stochastic generator with zero internal semantic verification capability — the tool is irrelevant, the process is determinative. The same agent that produces a plausible design or plausible code will produce a plausible-looking review of them. A human gate at design and merge is the only verification mechanism with the necessary independence *(IACDM — "verification gap"; State Contamination — memory laundering can preserve adversarial influence below classifier threshold. PRIME's executor/verifier agents are for algorithmic reasoning — sorting, automata — not TDD judge wiring)*.
 - **Gates are cheap; the work that gates prevent is expensive.** A five-minute human check at Gate 1 prevents a multi-day agent cycle that would have built the wrong thing. The economics favor verification early (Gate 1, design) and at the merge boundary (Gate 3, final audit) — but not in between, where a working agent loop is already verifiable on its own *(Agile-V — risk-adaptive acceptance at discrete levels rather than everywhere, always)*.
-- **"Do not let an agent implement from a long chat; let it implement from a reviewed brief."** Gates are the mechanism that converts a long conversation into a reviewed brief. The contract is what the agent implements against; the chat is at most a source of the contract. Without gates, the implementation drifts away from the original intent as the chat lengthens *(Agile-V / SCOPE-V — direct quote from the paper)*.
+- **"Do not let an agent implement from a long chat. Let it implement from a reviewed brief."** Gates are the mechanism that converts a long conversation into a reviewed brief. The contract is what the agent implements against; the chat is at most a source of the contract. Without gates, the implementation drifts away from the original intent as the chat lengthens *(Agile-V / SCOPE-V — direct quote from the paper)*.
 - **Two gates, not one and not ten.** One gate at the end is too late — errors have already cascaded. A gate at every micro-step is bureaucracy. Two gates correspond to the two failure modes that compound across the lifecycle: bad design (caught at Gate 1) and bad merge (caught at Gate 3). Each gate catches the class of error that the prior phases are most likely to produce. *_(The risk-adaptive framing is supported by Agile-V's R0–R3 acceptance levels; the specific count of two is DeviaTDD-original.)_
 
 ### Why the append-only ledgers exist
 
-- **Append-only is the merge strategy DeviaTDD uses to let parallel feature branches share state without coordination or a database.** Mutable state files would require lock-step coordination; a `.jsonl` file with `merge=union` declared in `.gitattributes` lets concurrent appends on parallel branches merge without conflict markers. The state machine scales beyond a single branch because the state format is append-only. *_(Git's `merge=union` is the structural basis. Parallel: TDFlow's repository-state-isolation principle. The "only viable strategy" claim is a software-engineering argument, not a research finding — see References §Gaps.)_*
+- **Append-only is the merge strategy DeviaTDD uses to let parallel feature branches share state without coordination or a database.** Mutable state files would require lock-step coordination; a `.jsonl` file with `merge=union` declared in `.gitattributes` lets concurrent appends on parallel branches merge without conflict markers. The state machine scales beyond a single branch because the state format is append-only. *_(Git's `merge=union` is the structural basis. TDFlow does not discuss worktrees, isolation, immutability, or branches — it is forced-decoupled sub-agents on SWE-bench given human-written tests. The "only viable strategy" claim is a software-engineering argument, not a research finding — see References §Gaps.)_*
 - **Deriving CLI state from the ledger, rather than caching it in a separate file, is what prevents state drift between the CLI and the repo.** The CLI's view of current task, active issue, completed work, and FR traceability is computed by sequential parsing of the ledger on demand. A separate state file would be a cache that could disagree with the source; a derived state cannot disagree with itself. *_(Design proposal — derived-state-from-log is a general software-engineering principle; no direct source supports the specific "sequential parse on demand, no cache" pattern.)_*
-- **Recording transitions as events, rather than mutating state in place, is what makes the ledger re-derivable from history.** An event can be replayed; a mutation cannot. A corrupted state file can be reconstructed by re-running the event stream, and the canonical state can always be recomputed by re-parsing the ledger *(parallel: PRIME — event-replayable State Stack)*.
+- **Recording transitions as events, rather than mutating state in place, is what makes the ledger re-derivable from history.** An event can be replayed; a mutation cannot. A corrupted state file can be reconstructed by re-running the event stream, and the canonical state can always be recomputed by re-parsing the ledger. *_(Design proposal — PRIME's opened abstract is algorithmic reasoning with an executor/verifier/coordinator, not an event-replayable git State Stack.)_*
 - **Deriving issue IDs from the ledger, rather than assigning them externally, is what makes them collision-free across parallel branches.** Externally-assigned IDs require coordination to avoid duplicates; ledger-derived IDs compute the next ID from the current ledger state and encode the issue's lineage by construction. The `next_issue_id` field on each shard contract is computed by parsing the ledger, not from a counter file. *_(Design proposal — the collision-free argument is a software-engineering claim, not a research finding.)_*
 - **`flow_refs:` in each issue's frontmatter is the only mechanism that connects a code change back to the customer flow that motivated it.** Without the trace, a refactor that "improves" a vertical slice may break the flow that motivated it without anyone noticing. The trace is what makes the issue→flow→release chain auditable. *_(The traceability principle is supported by SDD's spec-first case studies; the specific `flow_refs:` frontmatter convention is DeviaTDD-original.)_*
-- **A review surface and an execution surface serve different readers and must be separate files.** `tasks.md` is the only artifact a human can read, amend, and approve task decomposition against; `tasks.jsonl` is the only artifact a CLI can parse deterministically and replay across parallel branches. Combining them forces one format to compromise on both readers — a human-readable markdown becomes hard to parse, or a parseable JSONL becomes hard to review *(TDAD — `test_map.txt` vs `SKILL.md` separation; TDFlow)*.
+- **A review surface and an execution surface serve different readers and must be separate files.** `tasks.md` is the only artifact a human can read, amend, and approve task decomposition against; `tasks.jsonl` is the only artifact a CLI can parse deterministically and replay across parallel branches. Combining them forces one format to compromise on both readers — a human-readable markdown becomes hard to parse, or a parseable JSONL becomes hard to review *(TDAD — `test_map.txt` vs `SKILL.md` separation)*.
 
 ### Why the TDD micro-loop is `Red → Green → Judge/Train → Refactor`
 
@@ -316,7 +342,7 @@ The TDD micro-loop is what makes agent-written code trustworthy. Each phase exis
 
 #### Why Red (write a failing test first)
 
-- **Tests written after implementation tend to reflect what the code does, not what it should do.** When the same agent writes both test and implementation in one session, the implementation bleeds into the test — a failure mode known as *context pollution*. The test ends up passing trivially because it asserts whatever the implementation does, not whatever the spec requires. Forcing the test to be written first, in a session with no implementation, prevents the bleed *(TDAD — TDD Prompting Paradox; 70% regression reduction)*.
+- **Tests written after implementation tend to reflect what the code does, not what it should do.** When the same agent writes both test and implementation in one session, the implementation bleeds into the test — a failure mode known as *context pollution*. The test ends up passing trivially because it asserts whatever the implementation does, not whatever the spec requires. Forcing the test to be written first, in a session with no implementation, is DeviaTDD's structural counter to that bleed *(TDD Agent Dev; Refactor Pattern — context pollution when test and implementation share a session)*. TDAD is not evidence for red-first: its 70% regression cut (6.08% → 1.82%) and `SKILL.md` 107 → 20 / 12% → 50% are impact-map / `test_map.txt` results. The same paper's TDD Prompting Paradox: TDD instructions without a targeted test map *raised* regressions to 9.94%.
 - **A test that passes immediately is not a test.** Confirming the test fails before any production code exists verifies that the test actually exercises the new behavior. Skipping this step risks shipping a test that exercises nothing — green by construction, useless by construction.
 - **The test is the agent's only objective specification.** An agent given "make this work" produces plausible-looking code; an agent given "make this test pass" produces code whose correctness is mechanically checkable. The test is the only artifact in the loop that the agent cannot rationalize its way past *(TDD Agent Dev — tests as spec and guardrail)*.
 
@@ -328,11 +354,11 @@ The TDD micro-loop is what makes agent-written code trustworthy. Each phase exis
 
 #### Why Judge / Train (the Green → Judge → Green loop)
 
-- **The same agent that wrote the green code cannot reliably review it.** A self-review inherits the biases and blind spots of the producer — the same hallucinations, the same shortcuts, the same rationalizations. The Judge phase runs in an isolated session with a fresh context, breaking the recursive subjectivity of "did I do what I would have approved?" *(PRIME — Executor/Verifier separation; IACDM — external verification agents at discrete gates)*.
+- **The same agent that wrote the green code cannot reliably review it.** A self-review inherits the biases and blind spots of the producer — the same hallucinations, the same shortcuts, the same rationalizations. The Judge phase runs in an isolated session with a fresh context, breaking the recursive subjectivity of "did I do what I would have approved?" *(IACDM — external verification agents at discrete gates. PRIME's executor/verifier split is algorithmic-reasoning constraint checking, not a TDD judge)*.
 - **Tests passing is necessary but not sufficient.** A green test suite verifies the implementation matches the test; it does not verify the implementation matches the spec, the architecture, the security model, the performance budget, or the protected-module list. Judge evaluates the production diff against the contract for invariant, security, and structural violations the test cannot express. A separate human-style validation step at the end of an agentic session is required even when tests are green *(IACDM — verification gap; State Contamination — even classifier-cleaned memory can carry adversarial influence)*.
-- **Bounded repair with feedback injection converts failure into a learning signal.** When Judge rejects, the CLI rolls the task back to the RED commit (a known-good state), injects the failure feedback into the next GREEN prompt, and retries — up to three times. The next attempt has the same context plus the explicit feedback of why the previous attempt failed. This is the "Train" half: the failure is preserved as a constraint on the next attempt, not discarded as a dead end *(TDD Governance — N=3 repair cap with 4 validation gates; parallel: TDAD — feedback injection narrows surface area for regression)*.
+- **Bounded repair with feedback injection converts failure into a learning signal.** When Judge rejects, the CLI rolls the task back to the RED commit (a known-good state), injects the failure feedback into the next GREEN prompt, and retries — up to three times. The next attempt has the same context plus the explicit feedback of why the previous attempt failed. This is the "Train" half: the failure is preserved as a constraint on the next attempt, not discarded as a dead end *(TDD Governance — N=3 GREEN repair cap, a chosen bound; the paper has four *stages* — planning, generation, repair, validation — not "4 validation gates." Parallel: TDAD treats regression as a first-class metric via a targeted test map, not via red-first prompting)*.
 - **Three retries is enough; more would be a sign of a wrong test or a wrong spec.** A green implementation that fails Judge three times is unlikely to converge on the fourth. The bound forces escalation back to the human (an amendment, a new plan, or a spec revision) rather than burning compute on a fundamentally misaligned task. The empirical cap `N=3` is consistent with documented multi-agent TDD governance practice *(TDD Governance)*.
-- **Rollback is to a known-good commit, not a fresh start.** The RED commit is the verified-good test boundary. Resetting to it discards the suspect GREEN cleanly, but preserves all prior work — the test, the spec, the agent session, the audit trail. Starting from a fresh checkout would also discard the test, which is the only artifact whose correctness has actually been confirmed *(TDFlow — repository state isolation; TDD Governance — proposal-execution separation)*.
+- **Rollback is to a known-good commit, not a fresh start.** The RED commit is the verified-good test boundary. Resetting to it discards the suspect GREEN cleanly, but preserves all prior work — the test, the spec, the agent session, the audit trail. Starting from a fresh checkout would also discard the test, which is the only artifact whose correctness has actually been confirmed *(TDD Governance — proposal-execution separation. TDFlow does not discuss worktrees, isolation, or immutable branch state)*.
 
 #### Why Refactor (behavior-preserving improvement)
 
@@ -349,34 +375,34 @@ The rationale above grounds each architectural choice in published agentic-engin
 
 ### Methodology (de jure) — frameworks and governance
 
-- [**Agile-V / SCOPE-V**](https://arxiv.org/abs/2605.20456) — Agentic-Agile vs Vibe-Coding: Verified Engineering. Defines R0–R3 risk-adaptive acceptance; SCOPE-V's verify step at "before / during / before-merge / after-deployment"; "do not let an agent implement from a long chat; let it implement from a reviewed brief."
+- [**Agile-V / SCOPE-V**](https://arxiv.org/abs/2605.20456) — Agentic-Agile vs Vibe-Coding: Verified Engineering. Two layers (Agile-V lifecycle + SCOPE-V task loop), not Product/Macro/Meso/Micro. Defines R0–R3 risk-adaptive acceptance; SCOPE-V's verify step at "before / during / before-merge / after-deployment"; "Do not let an agent implement from a long chat. Let it implement from a reviewed brief."
 - [**IACDM**](https://arxiv.org/abs/2604.16399) — Interactive Adversarial Convergence Development Methodology. 8-phase framework with external verification agents at discrete gates; "the tool is irrelevant, the process is determinative"; foundational source for the "verification gap" rationale.
-- [**PRIME**](https://doi.org/10.20944/preprints202601.1479.v1) — Policy-Reinforced Iterative Multi-Agent Execution. Executor/Verifier asymmetry; event-replayable State Stack.
+- [**PRIME**](https://doi.org/10.20944/preprints202601.1479.v1) — Policy-Reinforced Iterative Multi-Agent Execution for Algorithmic Reasoning. Crossref abstract: executor / verifier / coordinator agents for sorting, automata, and state-machine tasks. Full text 403 on preprints.org. Not a git ledger or TDD judge paper.
 - [**State Contamination**](https://arxiv.org/abs/2605.16746) — State Contamination in Memory-Augmented LLM Agents. Memory laundering can preserve adversarial influence below classifier thresholds.
-- [**Survey**](https://doi.org/10.1007/s10462-2025-11422-4) — Agentic AI: A Comprehensive Survey of Architectures, Applications, and Future Directions. General multi-agent systems framing.
-- [**UCCI**](https://arxiv.org/abs/2605.18796) — Calibrated Uncertainty for Cost-Optimal LLM Cascade Routing. 31% cost reduction at matched accuracy via cascade routing by uncertainty margins.
-- [**RoBatch**](https://doi.org/10.14778/3734839.3734853) — Cost-Effective LLMs Routing with Batch Prompting. Amortizes system-prompt cost across batched calls.
+- [**Survey**](https://doi.org/10.1007/s10462-025-11422-4) — Agentic AI: A Comprehensive Survey of Architectures, Applications, and Future Directions ([arXiv:2510.25445](https://arxiv.org/abs/2510.25445)). Dual-paradigm review of neural vs symbolic agent architectures. Not a source for "conflating what/how/verify in one prompt."
+- [**UCCI**](https://arxiv.org/abs/2605.18796) — Calibrated Uncertainty for Cost-Optimal LLM Cascade Routing. 31% cost reduction at micro-F1 = 0.91 on a production NER workload (4B/12B cascade). Not coding-agent layer routing.
+- [**RoBatch**](https://doi.org/10.14778/3734839.3734853) — Optimized Batch Prompting for Cost-Effective LLMs. Batch prompting for data-management in-context learning. Not cascade routing of spec vs implement.
 
 ### Methodology (de jure) — process and decomposition
 
-- [**SDD**](https://arxiv.org/abs/2602.00180) — Spec-Driven Development: From Code to Contract. 4-phase workflow (Specify → Plan → Tasks → Implement); "passing spec tests only guarantee the code matches the spec"; 3–10× first-pass success via structured specs (EARS).
-- [**Spec Kit**](https://arxiv.org/abs/2604.05278) — Spec-Kit Agents: Context-Grounded Agentic Workflows. Discovery/validation hooks; co-located SPEC.md + PLAN.md + TASKS.md "intermediate artifacts" pattern.
-- [**Mise en Place**](https://arxiv.org/abs/2605.05400) — Mise en Place for Agentic Coding. Three-phase preparation methodology: contextual grounding, deliberate preparation, fresh-context per task.
-- [**Runtime Decomp**](https://arxiv.org/abs/2605.15425) — Runtime-Structured Task Decomposition for Agentic Coding Systems. Static decomposition 80.5% worse than runtime-branched; up to 51.7% lower retry cost.
+- [**SDD**](https://arxiv.org/abs/2602.00180) — Spec-Driven Development: From Code to Contract. Feature stages Specify → Plan → Implement → Validate (tools often add Tasks). "A passing spec test doesn't guarantee correct software—it only guarantees that the software matches the spec." Does **not** contain a 3–10× first-pass figure.
+- [**Spec Kit**](https://arxiv.org/abs/2604.05278) — Spec-Kit Agents: Context-Grounded Agentic Workflows. Feature stages Specify/Plan/Tasks/Implement with discovery/validation hooks; SPEC.md + PLAN.md + TASKS.md intermediate artifacts. Plan-review is optional (auto-approved in the study); a 40-minute arm skips those artifacts.
+- [**Mise en Place**](https://arxiv.org/abs/2605.05400) — Mise en Place for Agentic Coding. Three named phases: contextual grounding, collaborative specification, task decomposition. Does not name a "fresh-context per task" phase.
+- [**Runtime Decomp**](https://arxiv.org/abs/2605.15425) — Runtime-Structured Task Decomposition for Agentic Coding Systems. N=10, simulated failure: static retry cost exceeded monolithic by 80.5% (RCA); runtime-branched vs monolithic 51.7% lower retry cost, vs static 73.2%.
 
 ### Implementation (de facto) — TDD, agents, and refactor
 
-- [**TDAD**](https://arxiv.org/abs/2603.17973) — Test-Driven Agentic Development. TDD Prompting Paradox; `test_map.txt` vs `SKILL.md` separation; 70% regression reduction via pre-computed context artifacts; shrinking `SKILL.md` 107 → 20 lines quadrupled agent resolution 12% → 50%; "regression as first-class metric."
-- [**TDFlow**](https://arxiv.org/abs/2510.23761) — TDFlow: Agentic Workflows for Test-Driven Development. Forced-decoupling sub-agents; repository state isolation (diffs against the same baseline); immutable repo state between iterations.
-- [**TDDev**](https://arxiv.org/abs/2605.17242) — From Runnable to Shippable: Multi-Agent TDD. Protocol-model fit (conservative vs holistic models); vertical-slice protocols catch integration earlier than Agentic-TDD for conservative models.
-- [**TDD Governance**](https://arxiv.org/abs/2604.26615) — TDD Governance for Multi-Agent Code Generation. N=3 repair cap with 4 validation gates; design hygiene (refactor continuously while green); proposal-execution separation.
-- [**TDAID**](https://www.awesome-testing.com/2025/10/test-driven-ai-development-tdaid) — Test-Driven AI Development. Plan → Red → Green → Refactor → Validate cycle with bounded 15–60 min local commits per phase.
+- [**TDAD**](https://arxiv.org/abs/2603.17973) — Test-Driven Agentic Development. Impact-map / `test_map.txt` results: 70% regression reduction (6.08% → 1.82%); shrinking `SKILL.md` 107 → 20 lines raised resolution 12% → 50%. TDD Prompting Paradox: TDD instructions without a targeted test map raised regressions to 9.94%. Not a red-first proof.
+- [**TDFlow**](https://arxiv.org/abs/2510.23761) — TDFlow: Agentic Workflows for Test-Driven Development. Forced-decoupled sub-agents (propose / debug / revise / optional test generation) on SWE-bench given human-written tests. Does not discuss worktrees, isolation, immutability, branches, or append-only ledgers.
+- [**TDDev**](https://arxiv.org/abs/2605.17242) — From Runnable to Shippable: Multi-Agent TDD. Protocol-model fit: holistic models benefit from agentic TDD; conservative read-then-extend models benefit from incremental TDD. Does not use the word "vertical."
+- [**TDD Governance**](https://arxiv.org/abs/2604.26615) — TDD Governance for Multi-Agent Code Generation. N=3 GREEN repair cap (chosen bound); four *stages* (planning, generation, repair, validation); design hygiene (refactor continuously while green); proposal-execution separation.
+- [**TDAID**](https://www.awesome-testing.com/2025/10/test-driven-ai-development-tdaid) — Test-Driven AI Development. Plan → Red → Green → Refactor → Validate; local commits after each TDD phase. Does not state a 15–60 minute cycle.
 - [**Refactor Pattern**](https://agentpatterns.ai/verification/red-green-refactor-agents/) — Red-Green-Refactor with Agents: Tests as the Spec. Refactor must be behavior-preserving, never test-preserving; failed refactors are discarded.
 - [**TDD Agent Dev**](https://agentpatterns.ai/verification/tdd-agent-development/) — Test-Driven Agent Development: Tests as Spec and Guardrail. Tests-as-spec-guardrail pattern; structural enforcement against test-hacking.
 
 ### Specification and acceptance
 
-- [**Definitive SDD**](https://thebcms.com/blog/spec-driven-development) — Spec-Driven Development: The Definitive 2026 Guide. EARS notation (Ubiquitous / Event-driven / State-driven / Unwanted / Optional).
+- [**Definitive SDD**](https://thebcms.com/blog/spec-driven-development) — Spec-Driven Development: The Definitive 2026 Guide. EARS notation (Ubiquitous / Event-driven / State-driven / Unwanted / Optional). "~3–10× higher first-pass success rate from AI agents on non-trivial tasks, according to early adopter reports from GitHub and AWS."
 - [**Acceptance Test Gen**](https://arxiv.org/abs/2504.07244) — Acceptance Test Generation with LLMs (Industrial Case Study). 95% helpfulness, 92% semantic relevance, 60% directly usable as generated.
 - [**LLM BDD**](https://arxiv.org/abs/2403.14965) — Comprehensive Evaluation: LLMs for BDD Acceptance Test Formulation. Comprehensive evaluation of GPT-3.5/4, Llama-2, PaLM-2 on BDD generation.
 
@@ -388,11 +414,11 @@ The rationale above grounds each architectural choice in published agentic-engin
 
 Claims in this README flagged with an italic _design proposal_ note have **no direct source** in the agentic-engineering literature at the time of writing. They are explicit gaps in the evidence chain; treat them as DeviaTDD design choices, not research findings:
 
-- **Append-only JSONL over mutable state** — the "only viable merge strategy across parallel branches" claim is a software-engineering argument supported by git's `merge=union` semantics and TDFlow's parallel state-isolation work, not a direct research finding.
+- **Append-only JSONL over mutable state** — the "only viable merge strategy across parallel branches" claim is a software-engineering argument supported by git's `merge=union` semantics, not a research finding (TDFlow does not discuss isolation or ledgers).
 - **Product layer optionality; Flows / Architecture / Release triad; single-sentence release goal** — DeviaTDD-original; closest support is SDD's spec-from-plan-from-implementation separation at the feature level.
-- **4–8 tasks per issue** — the 15–60 min cycle target is supported (TDAID); the specific 4–8 count is not.
+- **4–8 tasks per issue** — DeviaTDD-original; TDAID does not state a 15–60 minute cycle.
 - **Per-issue Plan cadence; Adhoc complexity classifier; ledger-derived issue IDs; `flow_refs:` frontmatter convention; deriving CLI state from the ledger** — DeviaTDD-original; parallel support from adjacent work exists but does not directly cover these patterns.
-- **Two gates, not one and not ten** — the risk-adaptive framing is supported (Agile-V R0–R3); the specific count of two is DeviaTDD-original.
+- **Two gates, not one and not ten** — the risk-adaptive framing is supported (Agile-V R0–R3); the specific count of two is DeviaTDD-original. Design/contract review and merge review are the hard gates; shard is a soft review.
 
 ---