deviatdd 2.22.1__tar.gz → 2.23.1__tar.gz

deviatdd-2.23.1/.deviate/config.toml

@@ -0,0 +1,20 @@
+# Preset config group: "default", "full", "fast", or "secure"
+profile = "default"
+# CLI inactivity timeout in seconds (must be > 0)
+timeout_seconds = 1800
+# Agent export mode: "local" (project) or "global" (~/.claude/)
+agent_export_mode = "local"
+# Enable the libref CLI for offline documentation lookups
+use_libref = true
+# Trunk branch for worktrees, PR base, and review diffs
+base_branch = "main"
+# Push the claim branch as a distributed lock (default true)
+claim_remote = true
+
+# Agent backend configuration
+
+[agent]
+backend = "pi"
+timeout = 600
+pi_rpc = false
+transport = "rpc"

{deviatdd-2.22.1 → deviatdd-2.23.1}/CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **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`.
@@ -31,6 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`deviate html prd --bucket <slug>` targets a specific epic when more than one owns a `prd.md`.** Previously the command hard-failed with `HTML_AMBIGUOUS_PRD` whenever multiple numbered epics had a `prd.md` and offered no flag to disambiguate — the agent was told to "run from within the epic's worktree", which silently yielded `HTML_NO_PRD` because the resolver reads `specs/` from the repo root. The new option resolves `specs/<bucket>/prd.md` directly and bypasses ambiguity detection; the plain form keeps its existing behavior but its ambiguity banner now points at the flag. An unknown/absent bucket exits `PRD_NOT_FOUND`. The `/deviate-html` prompt (`src/deviate/prompts/commands/deviate-html.md`) and spec docs now reference `--bucket` instead of the broken cwd fallback. Pinned by `tests/test_cli/test_html.py::test_html_prd_bucket_targets_specific_epic`, `::test_html_prd_bucket_targets_unnumbered_dir`, and `::test_html_prd_bucket_missing_file_exits_cleanly`.
 - **Optional push-as-lock: `claim_remote` config plus `--local` on `meso run` and `run`.** Standing `.deviate/config.toml` key `claim_remote` 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`.
 ### Changed
+- **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`.
 - **JUDGE evidence is task-scoped; `deviate review` fail-closes on an unclaimed plan AC.** TDD `_run_judge_phase` resolves required `AC-PLAN-NNN` tokens via `resolve_task_ac_tokens` (non-empty `acceptance_criteria` `criterion_id`s, else this task's `tasks.md` card, else none) and does not fall back to every token in `plan.md`. ISS-ADH-020 exact-substring, path-in-diff, and uniqueness-floor checks still apply to that set. EXECUTE, IMMEDIATE, and DIRECT stay ungated. `deviate review pre` / `post` run a runner-owned Gate 3 scan (`evaluate_review_coverage`) and exit non-zero with `COVERAGE_INCOMPLETE` when any this-issue plan token has no COMPLETED claim. Missing `plan.md` or missing plan tokens stay vacuously READY. PENDING, FAILED, and sibling-issue rows do not claim. Pinned by `tests/test_core/test_judge_evidence.py`, `tests/test_micro/test_judge.py`, and `tests/test_cli/test_review.py`.
@@ -54,6 +56,13 @@ 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
+- **`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`.
+- **A `no_failing_test` already-exists JUDGE `COMPLIANCE_PASS` now completes via `skip_refactor` instead of hard-crashing with `ROLLBACK_BOUNDARY_MISSING`.** On the RED `no_failing_test` adjudication route (`session.failure_kind == "no_failing_test"`, `session.red_commit_sha == ""`), `_apply_judge_verdict` coerces any PASS `next_action` to `skip_refactor` through `_NO_FAILING_TEST_FORWARD_ROUTES`, skips the unmatched-PASS AC-token citation rewrite, and relaxes only the `COMPLETED_EVIDENCE_MISSING` token check for that route — the declared-regression-files gate (`_require_tdd_declared_regression_files`) stays fail-closed, a wrong test still routes to `revert_before` for RED re-author, and a genuine test-bearing RED with a real RED commit still rolls back via `revert_to_red`. Previously every retry crashed because the mechanical gate rewrote the pass to `revert_to_red` with no RED commit to roll back to. Specs updated: `specs/DeviaTDD-api.md`, `specs/DeviaTDD-architecture.md`. Pinned by `tests/test_micro/test_judge.py` and `tests/test_cli/test_micro.py`.
+- **Feature worktrees now base on the local trunk, so locally-authored (unpushed) issues plan without failing.** `resolve_start_point` (`src/deviate/core/worktree.py`) previously preferred `origin/<base>` over local `<base>`, so a `deviate meso run` that discovered an issue committed only to local `main` created its worktree from a stale `origin/main` that lacked the issue's `specs/issues.jsonl` row and source file — the plan agent wrote `plan.md`, then `deviate plan post` failed with `ISSUE_NOT_FOUND <IDS>` and exited 1. Meso reads the issue ledger from the local trunk, so the worktree base now comes from local `<base>` first (falling back to `origin/<base>`, then `HEAD`). Pinned by `tests/test_core/test_worktree.py::TestCreateWorktree::test_resolve_start_point_prefers_local_base_over_stale_origin`.
+- **`deviate meso run` / `deviate specify` auto-discovery now skips issues already claimed locally.** A claim writes the issue's `BACKLOG → SPECIFIED` ledger row in the new worktree and commits it on the `feat/{epic}/{issue}` feature branch, so the main checkout's `specs/issues.jsonl` still shows the issue as `BACKLOG`. `_discover_claimable_issue` therefore re-returned the same first issue to a second terminal on the same checkout (parallel run) instead of claiming a different one; the origin-branch lock only caught issues whose claim branch had been `git push`-ed. Discovery now also skips a candidate whose `feat/{epic}/{issue}` branch already has a local worktree (treated as claimed here), in both local and default mode, mirroring the signal `_try_claim_issue` already uses for `ALREADY_CLAIMED_LOCAL`. Two terminals on one checkout can now claim two different BACKLOG issues in parallel. Pinned by `tests/test_meso/test_meso_orchestration.py::TestDiscoverClaimableIssue::test_skips_issues_with_local_worktree`.
 - **`_append_judge_feedback` writes under the rejected task card, and the evidence gate keeps judge `train_feedback` / `violations` (GH-102).** The appender locates the card with `_TASK_BULLET_HEAD_RE` exact-id match (same regex as `_read_judge_feedback_from_tasks_md`) and stops at the next task or a `##` / `###` phase heading, so a Phase 1 `TSK-004-01` rejection no longer drops `**Judge Feedback**` under the next phase `### Tasks` / `TSK-004-02`. When the evidence gate rewrites unmatched PASS, persist the judge's own `train_feedback` / `violations` (after the GH-103 citation strip) instead of replacing them with the generic `JUDGE evidence is missing...` string. Pinned by `tests/test_micro/test_judge.py::TestJudgeFeedbackLogging::test_append_judge_feedback_stays_under_rejected_card_across_phase_header` and `TestTddJudgeEvidenceGate::test_rewritten_pass_keeps_judge_train_feedback` / `::test_rewritten_pass_keeps_judge_violations`.
 - **JUDGE injected diff walks past docs-feedback `red_commit_sha` to the real RED commit (GH-88, GH-90).** `_maybe_advance_red_sha_past_feedback` still advances the session SHA onto `docs(...): add judge feedback for retry` so GREEN entry and `revert_to_red` keep a valid TRAIN boundary. `_assemble_judge_injected_diff` now resolves the diff base via `_resolve_judge_diff_base`, walking back through those feedback subjects to the RED-phase failing-test commit and running `git diff {red_sha}^..HEAD`. The evidence gate no longer false-rejects with `test_path is not in the injected diff` or missing AC tokens solely because the RED test dropped out of a docs-only range. Pinned by `tests/test_micro/test_judge.py::TestJudgeDiffBaseWalksPastFeedback`.
 - **`resolve_task_ac_tokens` no longer treats runner-appended `**Judge Feedback**` as required AC tokens (GH-89).** Card-text fallback still follows first-hit order (`acceptance_criteria` `criterion_id`s, else the task card, else none) but now drops `**Judge Feedback**` bullets and their continuation lines before scanning for `AC-PLAN-NNN`. A feedback line quoting `AC-PLAN-001` does not add that token when the card body does not name it. `_task_card_text` still returns the full card. Pinned by `tests/test_core/test_judge_evidence.py::TestResolveTaskAcTokens::test_judge_feedback_quote_does_not_add_token`.

{deviatdd-2.22.1 → deviatdd-2.23.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: deviatdd
-Version: 2.22.1
+Version: 2.23.1
 Summary: DeviaTDD CLI — agent orchestration framework
 Project-URL: Homepage, https://github.com/wernerbisschoff/deviatdd
 Project-URL: Repository, https://github.com/wernerbisschoff/deviatdd
@@ -74,11 +74,11 @@ 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
+# governance blocks, and installs /deviate-* slash commands for the
+# selected agent only. The --agent flag picks the backend persisted to
+# .deviate/config.toml and is the only install target (`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.

{deviatdd-2.22.1 → deviatdd-2.23.1}/README.md

@@ -41,11 +41,11 @@ 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
+# governance blocks, and installs /deviate-* slash commands for the
+# selected agent only. The --agent flag picks the backend persisted to
+# .deviate/config.toml and is the only install target (`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.

{deviatdd-2.22.1 → deviatdd-2.23.1}/pyproject.toml

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

{deviatdd-2.22.1 → deviatdd-2.23.1}/specs/DeviaTDD-api.md

@@ -31,14 +31,15 @@ scripts. All commands are registered in `src/deviate/cli/__init__.py` using Type
   constitution. `deviate init pre` continues to scaffold the constitution independently.
   slash commands + 1 standalone `tools-mcp-servers` command (for Factory Droid)
   — 25 flat `.md` files total in the Factory install; 24 in every other agent
-  `.{agent}/prompts/` for Pi) during `deviate setup`. Commands land in all agent
-  directories — `.claude/commands/`, `.opencode/commands/`,
-  `.factory/commands/`, `.pi/prompts/`, `.omp/prompts/` — in a single invocation, regardless of which agent was passed
-  via `--agent`. Each command is a flat `<name>.md` file with a minimal YAML
-  frontmatter (`name:` + `description:`). The agent backend selected via `--agent`
-  (`opencode`, `claude`, `droid`, `factory`, `pi`, `omp`) is persisted to `[agent].backend` in
-  `config.toml` for use by the meso/micro layers; it does **not** gate which agent
-  directories receive commands.
+  `.{agent}/prompts/` for Pi) during `deviate setup`. Commands land only in the
+  selected agent's directory — `.claude/commands/`, `.opencode/commands/`,
+  `.factory/commands/` (`--agent factory` and `--agent droid`), `.pi/prompts/`,
+  `.omp/prompts/`, or Codex skills under `.agents/skills/<name>/SKILL.md`.
+  Each command is a flat `<name>.md` file (or a Codex `SKILL.md`) with a
+  minimal YAML frontmatter (`name:` + `description:`). The agent selected via
+  `--agent` (`opencode`, `claude`, `droid`, `factory`, `pi`, `omp`, `codex`)
+  is persisted to `[agent].backend` in `config.toml` and is the only install
+  target.
 
   **Single-source prompt derivation:** for each of the 11 overlapping phases
   (`explore`, `research`, `prd`, `shard`, `plan`, `tasks`, `red`, `green`,
@@ -84,8 +85,8 @@ scripts. All commands are registered in `src/deviate/cli/__init__.py` using Type
   duplicates rules), preserves user-authored `.gitattributes` content,
   and stages the file via `deviate init post` alongside the other
   scaffolded artifacts.
-* **Agent Selection:** Accepts `--agent [claude|opencode|droid|factory|pi]` to override
-  auto-detect. If omitted, the persisted value is reused; if no persisted value exists and
+* **Agent Selection:** Accepts `--agent [claude|opencode|droid|factory|pi|omp|codex]` to override
+  the persisted backend. If omitted, the persisted value is reused; if no persisted value exists and
   the session is interactive, a Rich `Prompt.ask` menu is shown. In non-interactive mode
   the command halts with `NO_AGENT_SELECTED` and a directive to re-run with `--agent`.
 * **Execution Modes:**
@@ -106,7 +107,7 @@ scripts. All commands are registered in `src/deviate/cli/__init__.py` using Type
   `${VARIABLE}` resolver described in earlier revisions of this spec has been removed.
 * **Input Parameters:**
   * `--agent-export-mode [local|global]` (Defaults to `local`)
-  * `--agent [claude|opencode|droid|factory|pi]` (Override auto-detect)
+  * `--agent [claude|opencode|droid|factory|pi|omp|codex]` (Override persisted backend)
   * `--no-claim-remote` (Disable push-as-lock; merges `claim_remote = false` into
   * `--libref` (Force-enable `libref` CLI integration; merges `use_libref = true` into
     `config.toml`)
@@ -134,9 +135,10 @@ scripts. All commands are registered in `src/deviate/cli/__init__.py` using Type
   * `specs/constitution.md` — Resolved boilerplate constitution
   * `AGENTS.md` — Symlink to `CLAUDE.md` (or vice-versa if only `AGENTS.md`
     existed pre-setup). Created by `_linkify_governance_files`; idempotent.
-  * `.claude/commands/`, `.opencode/commands/`, `.factory/commands/`,
-    supported agent (24 `deviate-*` + 1 standalone `tools-mcp-servers`
-    for Factory = 25 flat `.md` files total in that one directory)
+  * Selected-agent command install only: `.claude/commands/`,
+    `.opencode/commands/`, `.factory/commands/`, `.pi/prompts/`,
+    `.omp/prompts/`, or `.agents/skills/<name>/SKILL.md` for Codex.
+    Factory also receives the standalone `tools-mcp-servers` command.
 
 #### `deviatdd` Skill (Project-Local Single Skill)
 
@@ -147,21 +149,19 @@ scripts. All commands are registered in `src/deviate/cli/__init__.py` using Type
   `src/deviate/cli/__init__.py`, called from `setup()` after
   `_install_commands_to_agents(...)`. Idempotent (content-equality skip
   mirrors `install_command`'s contract).
-* **Install targets (all five `active_agents`):** the skill is written
-  to `<workdir>/.<agent>/skills/deviatdd/SKILL.md` for every agent
-  platform that `setup` provisions commands for, regardless of whether
-  each platform documents a project-local skills convention. Mirrors
-  `_install_commands_to_agents`'s write-everywhere policy — every
-  operator using `--agent <platform>` gets the skill at the canonical
-  skills directory for their platform, ready to be picked up if/when
-  that platform ships a discovery convention.
+* **Install target (selected agent only):** the skill is written to
+  `<workdir>/.<agent>/skills/deviatdd/SKILL.md` for the agent passed to
+  `--agent` (or the persisted backend / interactive prompt). `droid`
+  normalizes to `factory`. Codex writes
+  `<workdir>/.agents/skills/deviatdd/SKILL.md` and does **not** write
+  `.codex/prompts` or `.codex/commands`.
   * `claude` -> `<workdir>/.claude/skills/deviatdd/SKILL.md`
     (verified — same form as user-level `~/.claude/skills/<name>/SKILL.md`).
   * `opencode` -> `<workdir>/.opencode/skills/deviatdd/SKILL.md`
     (no documented project-local skills convention; file on disk for
     forward-compat).
   * `factory` -> `<workdir>/.factory/skills/deviatdd/SKILL.md`
-    (same as opencode).
+    (same as opencode; `--agent droid` uses this path).
   * `pi` -> `<workdir>/.pi/skills/deviatdd/SKILL.md`
     (verified — `pi@latest` docs at
     `packages/coding-agent/docs/skills.md` list `.pi/skills/` as a
@@ -171,6 +171,9 @@ scripts. All commands are registered in `src/deviate/cli/__init__.py` using Type
     `~/.omp/agent/managed-skills/<name>/SKILL.md` and via a
     settings-driven `skills` array; operators can register the
     project-local file via OMP's settings).
+  * `codex` -> `<workdir>/.agents/skills/deviatdd/SKILL.md`
+    (Codex CLI 0.117+ official project-local discovery). Each packaged
+    slash command is also installed as `.agents/skills/<name>/SKILL.md`.
 * **Scope:** Unified Meso and Micro orchestration. The skill first runs
   `deviate meso run`. In an existing feature worktree, the runner validates
   `plan.md` and `tasks.md`, skips completed phases, and resumes at Tasks when
@@ -218,14 +221,17 @@ scripts. All commands are registered in `src/deviate/cli/__init__.py` using Type
 * **`.gitignore` exclusions:** `_ensure_root_gitignore` adds
   `*/skills/deviatdd/` to the entries tuple alongside
   `*/commands/deviate-*.md` and `*/prompts/deviate-*.md`. The
-  single-level wildcard covers all five agent platforms
-  (`.claude/`, `.opencode/`, `.factory/`, `.pi/`, `.omp/`) with one
-  pattern. The single-level prefix (`*/`, not `**/`) is critical: it
+  single-level wildcard covers every selected-agent skill install
+  (`.claude/`, `.opencode/`, `.factory/`, `.pi/`, `.omp/`, `.agents/`)
+  with one pattern. `*/skills/deviate-*/` covers Codex per-command
+  skill dirs. The single-level prefix (`*/`, not `**/`) is critical: it
   scopes the pattern to the project root, never matching the
   source-of-truth at `src/deviate/prompts/skills/deviatdd/` (three
   directories deep).
-* **Tests:** `TestInstallDeviatddSkill` (8 tests) in
-  `tests/test_cli/test_init.py` covers install-to-all-five-agents,
+* **Tests:** `TestInstallDeviatddSkill` in
+  `tests/test_cli/test_init.py` and `TestSetupSelectedAgentIsolation` /
+  `TestSetupCodex` in `tests/test_cli/test_setup.py` cover
+  selected-agent-only install, Codex skills + `backend = "codex"`,
   idempotence, gitignore entry presence + idempotence, safety-gate
   fragments in the SKILL.md body, well-formed frontmatter, and the
   dispatch table's canonical slash-command references.
@@ -257,7 +263,7 @@ scripts. All commands are registered in `src/deviate/cli/__init__.py` using Type
 
 ### 1.5 Product Layer *(optional, sits above Macro)*
 
-The Product layer ships as **agent skills** (no dedicated CLI subcommands) — the prompts live at `src/deviate/prompts/commands/deviate-{flows,architecture,release}.md` and are installed to all four agent directories alongside the rest. They are **not** wired into the `deviate` CLI's `pre`/`post` subcommand pattern: the agent invokes them directly as `/deviate-flows`, `/deviate-architecture`, `/deviate-release`, and the conversation produces the artifact. The CLI's only involvement is installing the skill files during `deviate setup` and (via `deviate-shard` / `deviate-adhoc`) consuming the `flow_refs:` frontmatter those artifacts emit.
+The Product layer ships as **agent skills** (no dedicated CLI subcommands) — the prompts live at `src/deviate/prompts/commands/deviate-{flows,architecture,release}.md` and are installed to the selected agent directory alongside the rest. They are **not** wired into the `deviate` CLI's `pre`/`post` subcommand pattern: the agent invokes them directly as `/deviate-flows`, `/deviate-architecture`, `/deviate-release`, and the conversation produces the artifact. The CLI's only involvement is installing the skill files during `deviate setup` and (via `deviate-shard` / `deviate-adhoc`) consuming the `flow_refs:` frontmatter those artifacts emit.
 
 | Command | Source skill | Artifact committed | Notes |
 |---------|--------------|--------------------|-------|
@@ -436,7 +442,10 @@ accepts `--json` (emit JSON contract to stdout) and `--quiet` (suppress output).
   claims that specific issue. With **no argument**, auto-discovers the next claimable
   BACKLOG issue via `_discover_claimable_issue()` (the same discovery `deviate meso run`
   uses) and claims it. Default discovery skips issues whose `feat/{epic}/{issue}` branch
-  already exists on remote (treated as claimed elsewhere). Local mode does not skip those
+  already exists on remote (treated as claimed elsewhere). In any mode it also skips
+  issues whose `feat/{epic}/{issue}` branch already has a local worktree (treated as claimed
+  here) — that local-worktree guard is what lets two parallel terminals claim two different
+  BACKLOG issues without re-claiming the same one. Local mode does not skip those
   origin branches. Stops after the worktree is created and the claim is committed — does
   NOT advance session state and does NOT run plan or tasks. To continue, run
   ``deviate plan pre`` or invoke the ``/deviate-plan`` slash command inside the new
@@ -594,9 +603,16 @@ accepts `--json` and `--quiet`. `pre` emits a JSON contract describing the envir
   in the injected ``<diff>`` or HEAD (constitution §3 Testing Protocols; §5 Definition of Done).
   Empty ``files`` / ``test_file`` is a RED defect (``PhaseFailedError``); the ledger writes no
   COMPLETED row. JUDGE ``skip_refactor`` / bare ``COMPLIANCE_PASS`` keeps those declared tests
-  on disk via ``_restore_worktree_to_baseline(..., keep_paths=declared)``. A declared path
-  missing from the snapshot rewrites PASS to ``revert_before`` / ``revert_to_red``. JUDGE still
-  rules a wrong test as ``revert_before`` so RED re-authors a genuinely failing test. EXECUTE,
+  on disk via ``_restore_worktree_to_baseline(..., keep_paths=declared)``. On the already-exists
+  route (``session.red_commit_sha == ''``), a ``no_failing_test`` ``COMPLIANCE_PASS`` with any
+  ``next_action`` completes via ``skip_refactor`` even when the evidence cites only part of the
+  task's ``AC-PLAN-NNN`` tokens: ``_apply_judge_verdict`` skips the unmatched-PASS rewrite for
+  this route, and ``_require_tdd_completed_evidence`` relaxes the AC-token citation check while
+  keeping the declared regression-path presence gate. ``ROLLBACK_BOUNDARY_MISSING`` applies only
+  to a genuine TDD ``revert_to_red`` with an empty ``red_commit_sha`` — never on the
+  already-exists pass path. A declared path missing from the snapshot rewrites PASS to
+  ``revert_before`` / ``revert_to_red``. JUDGE still rules a wrong test as ``revert_before`` so
+  RED re-authors a genuinely failing test. EXECUTE,
   IMMEDIATE, and DIRECT stay ungated by this files rule. After ``revert_before`` / cycle
   ``no_failing_test_adjudicated``, the next ``INVOKE_AGENT`` is RED, or the loop raises
   ``TRAIN_EXHAUSTED`` / ``PhaseFailedError``. It never invokes GREEN while
@@ -946,7 +962,7 @@ accepts `--json` and `--quiet`. `pre` emits a JSON contract describing the envir
   populated `parse_errors` list and
   `HandoverManifest.is_success` returns `False` so existing
   `manifest.status.upper() in (...)` success gates keep rejecting them.
-  (6) **Stricter mapping fallback** — the `_YAML_MAPPING_START_RE` fallback (`src/deviate/core/agent.py`) routes the candidate text through a `_looks_like_manifest` helper that requires `yaml.safe_load(candidate)` to return a `dict` with at least 2 keys before accepting. Single-key dicts (e.g. a stray `Status: complete` line in a JUDGE verdict with a verification matrix) look like prose, not manifests; the fallback now rejects them and the parser raises `MalformedHandoverManifestError` with the existing "No YAML handover manifest detected in agent output" hint. Multi-key partial dicts still flow through to schema recovery unchanged, so the existing `test_missing_phase_and_status_recover_as_unknown` contract is preserved.
+  (6) **Stricter mapping fallback** — the `_YAML_MAPPING_START_RE` fallback (`src/deviate/core/agent.py`) routes the candidate text through a `_looks_like_manifest` helper that requires `yaml.safe_load(candidate)` to return a `dict` with at least 2 keys before accepting. Single-key dicts (e.g. a stray `Status: complete` line in a JUDGE verdict with a verification matrix) look like prose, not manifests; the fallback now rejects them and the parser raises `MalformedHandoverManifestError` with the existing "No YAML handover manifest detected in agent output" hint. Multi-key partial dicts still flow through to schema recovery unchanged, so the existing `test_missing_phase_and_status_recover_as_unknown` contract is preserved. (6b) **Unescaped evidence-quote recovery (GH-116)** — when `yaml.safe_load` rejects a handover because an evidence `quote` / `test_quote` / `impl_quote` double-quoted scalar embeds raw `"`, `parse_output` rewrites those lines as `|` block scalars and reloads. Well-formed YAML is unchanged. Truly malformed YAML still raises `MalformedHandoverManifestError`. Verdict and evidence semantics are unchanged.
   (7) **Lean Pi spawn** — `AgentBackend.invoke` appends a lean tool policy after the existing Pi transport prefix. Print mode keeps `BACKEND_COMMANDS["pi"]` as `pi -p` (AC-009-07). RPC keeps `PI_RPC_COMMAND` as `pi --mode rpc --no-session` (AC-009-10). The helper `_pi_lean_flags` then adds `--no-extensions`, `--tools read,bash,edit,write`, and `--no-skills`. When `.pi/skills/deviatdd/SKILL.md` exists under the invoke `cwd` (or `Path.cwd()`), it also adds `--skill` to that relative path. A missing skill file keeps the four coding tools. The argv omits `--no-tools` and `--no-builtin-tools`. Non-Pi backends skip these flags.
   (8) **Schema-rejection fail-fast** — `_invoke_streaming`, `_invoke_blocking`, and `_invoke_rpc_blocking` scan each stderr and stdout line. The first line that contains `tool_count_limit` or `unsupported_tool_schema` kills the child. The helper raises `AgentSubprocessError` whose message carries those tokens. This path does not wait for `STREAM_STALL_TIMEOUT_SECONDS` (900s). It does not start the 30s timeout retry. It does not start the `EmptyOutputError` manifest retry. Schema tokens do not reset the stall clock. Stderr stays diagnostic for stall liveness (ISS-ADH-025). `_invoke_agent` logs `AGENT_ERROR` with the exception text. `_raise_schema_limit_phase_error` then raises `PhaseFailedError` so `deviate micro run` RED, GREEN, and REFACTOR include the tokens. The operator does not see only `agent returned no manifest`. EXECUTE stall stays 3600s (GH-53).
 * **GREEN Stub-PASS Guard (REMOVED):** An earlier revision of this spec
@@ -1483,7 +1499,11 @@ All state transitions are append-only. No existing line is ever modified or over
 - `append_issue_transition()`: Idempotent on `(issue_id, status)` compound key
 - `append_task_transition()`: Idempotent on `(id, status)` compound key
 - `_append_record()` / `_append_with_compound_key()`: Use `fcntl.flock` for file-level
-  locking on platforms that support it
+  locking on platforms that support it. If the ledger is non-empty and the last
+  line has no trailing newline, a leading `\n` is written before the new record
+  so two JSON objects never share a line. Every successful write leaves a trailing
+  newline. `claim_issue` writes through `append_issue_transition` (not a raw `"a"`
+  append).
 - Canonical state: Issues derived bottom-up (latest entry per `issue_id`); tasks derived
   sequentially (latest entry per `(id, status)` compound key)
 
@@ -1540,7 +1560,7 @@ the action. EXECUTE `_run_execute_phase` and IMMEDIATE judge stay ungated.
 
 **Empty-diff sign-off:** `proceed_to_refactor_no_diff` (`src/deviate/cli/micro.py::_run_judge_phase`) is the forward-route escape for slices whose production-code scope is intrinsically nil — RED-only deliverable, fixture file, generated types, doc-only slice, or any task whose `failure_kind: mechanical` rationale asserts "no production code expected." The TDD evidence gate still requires a dirty-diff `test_quote` and omits `impl_quote`. The JUDGE-side responsibility is to emit the action on a `COMPLIANCE_PASS` verdict when the in-scope rationale is valid but the production diff cannot grow. The action lands the task at REFACTOR's no-op commit + COMPLETED transition in one step; unmatched empty-GREEN PASS does not COMPLETE.
 
-**TDD mechanical evidence gate:** `HandoverManifest.evidence` is a first-class list of nested citations (`ac`, `test_path`, `test_quote`, `impl_path`, `impl_quote`) in `src/deviate/core/agent.py`. After `_coerce_judge_action`, TDD `_run_judge_phase` (`src/deviate/cli/micro.py`) resolves this task's required `AC-PLAN-NNN` tokens via `resolve_task_ac_tokens` (`src/deviate/core/judge_evidence.py`) and passes that list as `required_tokens` to `evaluate_judge_evidence`. First hit wins: non-empty `TaskRecord.acceptance_criteria` `criterion_id`s; else `AC-PLAN-NNN` tokens named in this task's `tasks.md` card after dropping `**Judge Feedback**` bullets and their continuation lines; else no AC tokens. The gate does not fall back to every token in `<authoritative_acceptance_contract source="plan.md">`. Omitting a later-shard plan token is legal at JUDGE. Auto and manual judge prompts require `evidence` only for the resolved task tokens. Quotes must copy from the already-built `<diff>` (`git diff <red>^..HEAD` where `<red>` is `_resolve_judge_diff_base(session.red_commit_sha)` — the RED-phase failing-test commit after walking back through `docs(...): add judge feedback for retry` subjects — plus dirty `git diff HEAD` and untracked `--no-index` hunks) or allowed HEAD files. ISS-ADH-020 quote checks still apply to that task set: missing this-task tokens, empty quotes, hallucinated paths, quotes below the uniqueness floor (≥ 12 non-whitespace characters, or the full added line if shorter), or quotes that are not exact substrings of the named file hunk rewrite the action to `revert_to_red` with runner-authored feedback in the `JUDGE_AGENT_NO_FEEDBACK` family. When the judge already emitted `train_feedback` or `violations`, persist that text (after the GH-103 citation strip) instead of replacing it with the generic missing-evidence string (GH-102). The task does not COMPLETE. `skip_refactor` on the already-exists path may quote HEAD file contents for this-task tokens; a named test file absent on disk fails. On a test-bearing TDD already-exists claim, every declared `files` / `test_file` path (and evidence `test_path`) must appear in `_assemble_judge_injected_diff` or `_evidence_head_contents`. The membership check runs even when the resolved set has no `AC-PLAN-*` tokens. Empty declared files remain a RED defect, not a COMPLETE. Tasks with no resolved `AC-PLAN-*` tokens may emit empty evidence quotes, but they still need named present test paths. `COMPLIANCE_VIOLATION` skips the quote gate. After the gate returns no feedback and the action is a completion path (`skip_refactor` / bare `COMPLIANCE_PASS` / post-REFACTOR complete / adjudicated already-exists), `_append_status_transition(..., "COMPLETED")` copies the validated `HandoverManifest.evidence` onto that COMPLETED `TaskRecord` as `evidence.items` and stamps `red` / `green` / `head` from `session.red_commit_sha` and `HEAD` (GH-84). TDD complete fail-closes when the injected plan contract has `AC-PLAN-NNN` tokens and the persisted bundle is missing or does not cover them — the same `evaluate_judge_evidence` matcher, with `use_head=True` so quotes resolve against HEAD at the COMPLETED write. Plans with no `AC-PLAN-*` tokens may complete with empty evidence. EXECUTE, IMMEDIATE, and DIRECT judge paths stay ungated.
+**TDD mechanical evidence gate:** `HandoverManifest.evidence` is a first-class list of nested citations (`ac`, `test_path`, `test_quote`, `impl_path`, `impl_quote`) in `src/deviate/core/agent.py`. After `_coerce_judge_action`, TDD `_run_judge_phase` (`src/deviate/cli/micro.py`) resolves this task's required `AC-PLAN-NNN` tokens via `resolve_task_ac_tokens` (`src/deviate/core/judge_evidence.py`) and passes that list as `required_tokens` to `evaluate_judge_evidence`. First hit wins: non-empty `TaskRecord.acceptance_criteria` `criterion_id`s; else `AC-PLAN-NNN` tokens named in this task's `tasks.md` card after dropping `**Judge Feedback**` bullets and their continuation lines; else no AC tokens. Auto `_build_auto_prompt("judge")` injects that same stripped card as `<task_card source="tasks.md">` (GH-118); `_task_card_text` still returns the raw card for token resolution, GREEN `<persisted_judge_feedback>`, and file-list parsing. The gate does not fall back to every token in `<authoritative_acceptance_contract source="plan.md">`. Omitting a later-shard plan token is legal at JUDGE. Auto and manual judge prompts require `evidence` only for the resolved task tokens. Quotes must copy from the already-built `<diff>` (`git diff <red>^..HEAD` where `<red>` is `_resolve_judge_diff_base(session.red_commit_sha)` — the RED-phase failing-test commit after walking back through `docs(...): add judge feedback for retry` subjects — plus dirty `git diff HEAD` and untracked `--no-index` hunks) or allowed HEAD files. ISS-ADH-020 quote checks still apply to that task set: missing this-task tokens, empty quotes, hallucinated paths, quotes below the uniqueness floor (≥ 12 non-whitespace characters, or the full added line if shorter), or quotes that are not exact substrings of the named file hunk rewrite the action to `revert_to_red` with runner-authored feedback in the `JUDGE_AGENT_NO_FEEDBACK` family. When the judge already emitted `train_feedback` or `violations`, persist that text (after the GH-103 citation strip) instead of replacing it with the generic missing-evidence string (GH-102). The task does not COMPLETE. `skip_refactor` on the already-exists path may quote HEAD file contents for this-task tokens; a named test file absent on disk fails. On a test-bearing TDD already-exists claim, every declared `files` / `test_file` path (and evidence `test_path`) must appear in `_assemble_judge_injected_diff` or `_evidence_head_contents`. The membership check runs even when the resolved set has no `AC-PLAN-*` tokens. Empty declared files remain a RED defect, not a COMPLETE. Tasks with no resolved `AC-PLAN-*` tokens may emit empty evidence quotes, but they still need named present test paths. `COMPLIANCE_VIOLATION` skips the quote gate. After the gate returns no feedback and the action is a completion path (`skip_refactor` / bare `COMPLIANCE_PASS` / post-REFACTOR complete / adjudicated already-exists), `_append_status_transition(..., "COMPLETED")` copies the validated `HandoverManifest.evidence` onto that COMPLETED `TaskRecord` as `evidence.items` and stamps `red` / `green` / `head` from `session.red_commit_sha` and `HEAD` (GH-84). TDD complete fail-closes when the injected plan contract has `AC-PLAN-NNN` tokens and the persisted bundle is missing or does not cover them — the same `evaluate_judge_evidence` matcher, with `use_head=True` so quotes resolve against HEAD at the COMPLETED write. Plans with no `AC-PLAN-*` tokens may complete with empty evidence. EXECUTE, IMMEDIATE, and DIRECT judge paths stay ungated.
 
 **Feedback-commit timeout:** The `revert_to_red` step's "append a feedback
 commit past RED" runs `_commit_judge_feedback_and_advance`

{deviatdd-2.22.1 → deviatdd-2.23.1}/specs/DeviaTDD-architecture.md

@@ -285,9 +285,9 @@ to invoke, but model selection is delegated to the calling environment.
     * **Layer discipline:** GREEN's only invariant is "make the RED test pass via the library/API surface declared in scope." It does NOT make scope, spec-drift, or HITL-routing judgments — those belong to JUDGE. When a RED test cannot be satisfied within GREEN's mechanical scope, GREEN emits `status: FAILURE` with a concrete `rationale:` naming the test path and why; `status: "ERROR"` is reserved strictly for tool/orchestration failure. The runner's `_is_hitl_escalation` is a narrow defensive fallback that ONLY promotes structured `contract_drift` / `escalates_to` / `hitl_options` dict keys to `HITL_PENDING` — loose-string `error_kind` discriminators and free-form scope-conflict text do NOT trigger HITL escalation.
     * **Mechanical Failure → JUDGE Routing:** When GREEN emits `status: FAILURE` with a concrete `rationale:` (the mechanical scope-boundary case above), the runner routes control to JUDGE instead of raising `PhaseFailedError`. `_run_green_phase` sets `session.train_feedback = rationale` + `session.failure_kind = "mechanical"` and returns the session; `_run_judge_phase` injects a `<failure_kind>mechanical</failure_kind>` discriminator block into the JUDGE prompt that instructs the agent to emit `verdict: COMPLIANCE_PASS` + `next_action: proceed_to_refactor_no_diff` (when the slice is intrinsically RED-only and REFACTOR's no-op commit + COMPLETED transition is the right termination) OR `verdict: COMPLIANCE_VIOLATION` + one of three `next_action` values (`revert_before` / `revert_to_red` / `skip_refactor`) instead of attempting to satisfy the test itself. This closes the loop where mechanical FAILURE (e.g. slice-scope conflict, CLI-surface-out-of-sco…
     * **Test-Defect Failure → JUDGE Routing:** A second routable failure class, parallel to mechanical but pre-decided. When GREEN observes that the RED test itself is wrong (it asserts behavior the spec does not require, exercises the wrong abstraction, or encodes an assumption that contradicts spec/data-model), GREEN emits `status: FAILURE` with a concrete `rationale:` citing the FR/AC the test contradicts, plus `failure_kind: test_defect` on the manifest (`HandoverManifest.failure_kind: Literal["mechanical", "test_defect", "already_satisfied"] | None` in `src/deviate/core/agent.py` — session mirrors the discriminator as `SessionState.failure_kind: Literal["", "mechanical", "test_defect", "no_failing_test"]` in `src/deviate/state/config.py`). `_run_green_phase` reads the manifest's discriminator, sets `session.failure_kind = "test_defect"`, and routes to JUDGE. `_run_judge_phase` injects a `<failure_kind>test_defect</failure_kind>` discriminator block that pre-decides the routing — `verdict: COMPLIANCE_VIOLATION` + `next_action: revert_before` (re-run RED with the GREEN rationale as feedback) — because test defect has only one sensible outcome: the test itself must be re-authored. The discriminator intentionally narrows the JUDGE routing vocabulary compared to mechanical (`revert_to_red` / `skip_refactor` / `proceed_to_refactor_no_diff` are NOT options in the test_defect block). Default `manifest.failure_kind = None` falls through to `"mechanical"` in the runner to preserve prior behavior.
-    * **RED No-Failing-Test → JUDGE Adjudication (RED → JUDGE direct route):** When RED completes but its test command exits 0 (all tests passed), collects no tests (pytest exit 5), or resolves to no command at all (returncode 127 from `_run_test_cmd`), `_run_red_phase` does NOT raise a raw `PhaseFailedError` and does NOT let GREEN run against a vacuous test. It calls `_adjudicate_red_no_failing_test` (`src/deviate/cli/micro.py`), which sets `session.failure_kind = "no_failing_test"`, injects a `<failure_kind>no_failing_test</failure_kind>` discriminator block into the JUDGE prompt, and dispatches `_run_judge_phase(...)`. The judge diff spans the uncommitted RED test (the `red_baseline` parameter makes `_run_judge_phase` skip the `RED→HEAD` committed diff and surface the agent's uncommitted test through the dirty-parts scan) so JUDGE reviews what the agent actually wrote. On a test-bearing TDD task, `_require_tdd_declared_regression_files` requires a non-empty `files` set and/or `test_file` before this COMPLETE route (constitution §3 Testing Protocols; §5 Definition of Done). Empty declared files raise `PhaseFailedError`. JUDGE decides between two outcomes: `verdict: COMPLIANCE_PASS` + `next_action: skip_refactor` (or a bare PASS verdict) when the required behavior already exists and every declared regression path sits in the injected `<diff>` or `_evidence_head_contents` — the runner then calls `_restore_worktree_to_baseline(..., keep_paths=declared)` so those tests stay on disk, and marks the task COMPLETED; a declared path missing from that snapshot rewrites PASS to `revert_before` / `revert_to_red` with runner-authored feedback and writes no COMPLETED row; or `verdict: COMPLIANCE_VIOLATION` + `next_action: revert_before` (forced by the `_coerce_judge_action` runner-level override for `failure_kind` `no_failing_test`/`test_defect`) when the test is wrong — the runner resets to the RED baseline and re-dispatches RED so a fresh genuinely-failing test is authored. EXECUTE, IMMEDIATE, and DIRECT stay ungated by the files rule. The next `INVOKE_AGENT` is RED, or the loop raises `TRAIN_EXHAUSTED` / `PhaseFailedError`. It never invokes GREEN while `session.red_commit_sha` is empty. `--no-judge` makes the no-failing-test outcome a hard failure (adjudication disabled). Test discovery is language-agnostic: the RED gate no longer globs Python `tests/**/test_*.py` (`_find_test_files`); the project's own convention is honored through the resolved test command (e.g. `mix test` collecting `test/**/*_test.exs` for Elixir/Phoenix), so a correctly authored non-Python test is neither rejected up front nor silently conflated with "no test framework" — a project with no resolvable test command routes to the same JUDGE adjudication instead of failing. This closes the prior stall where an empty `_find_test_files` let RED silently commit a vacuous 'failing test' and GREEN die in `TRAIN_EXHAUSTED`. The RED agent may steer the adjudication by declaring `failure_kind: already_satisfied` (behavior exists) with a non-empty `files` set and/or `test_file`, or `failure_kind: test_defect` (test wrong) with a `rationale` on its handover manifest. A passing suite with no named test files is not a COMPLETE.
+    * **RED No-Failing-Test → JUDGE Adjudication (RED → JUDGE direct route):** When RED completes but its test command exits 0 (all tests passed), collects no tests (pytest exit 5), or resolves to no command at all (returncode 127 from `_run_test_cmd`), `_run_red_phase` does NOT raise a raw `PhaseFailedError` and does NOT let GREEN run against a vacuous test. It calls `_adjudicate_red_no_failing_test` (`src/deviate/cli/micro.py`), which sets `session.failure_kind = "no_failing_test"`, injects a `<failure_kind>no_failing_test</failure_kind>` discriminator block into the JUDGE prompt, and dispatches `_run_judge_phase(...)`. The judge diff spans the uncommitted RED test (the `red_baseline` parameter makes `_run_judge_phase` skip the `RED→HEAD` committed diff and surface the agent's uncommitted test through the dirty-parts scan) so JUDGE reviews what the agent actually wrote. On a test-bearing TDD task, `_require_tdd_declared_regression_files` requires a non-empty `files` set and/or `test_file` before this COMPLETE route (constitution §3 Testing Protocols; §5 Definition of Done). Empty declared files raise `PhaseFailedError`. JUDGE decides between two outcomes: `verdict: COMPLIANCE_PASS` + `next_action: skip_refactor` (or a bare PASS verdict, or any `next_action` on the already-exists route) when the required behavior already exists and every declared regression path sits in the injected `<diff>` or `_evidence_head_contents` — `_apply_judge_verdict` then coerces the action to `skip_refactor`, skips the `_rewrite_unmatched_tdd_pass` AC-token citation rewrite for this route, and `_require_tdd_completed_evidence` relaxes the AC-token citation check while retaining the declared-path presence gate, so partial evidence completes instead of rewriting to `revert_to_red`; the runner then calls `_restore_worktree_to_baseline(..., keep_paths=declared)` so those tests stay on disk, and marks the task COMPLETED. `_require_revert_to_red_boundary` is never invoked on this already-exists pass path, so `ROLLBACK_BOUNDARY_MISSING` applies only to a genuine TDD `revert_to_red` with an empty `red_commit_sha`. A declared path missing from that snapshot still fails closed via `_require_tdd_declared_regression_files` (rewriting PASS to `revert_before` / `revert_to_red` with runner-authored feedback and writing no COMPLETED row); or `verdict: COMPLIANCE_VIOLATION` + `next_action: revert_before` (forced by the `_coerce_judge_action` runner-level override for `failure_kind` `no_failing_test`/`test_defect`) when the test is wrong — the runner resets to the RED baseline and re-dispatches RED so a fresh genuinely-failing test is authored. EXECUTE, IMMEDIATE, and DIRECT stay ungated by the files rule. The next `INVOKE_AGENT` is RED, or the loop raises `TRAIN_EXHAUSTED` / `PhaseFailedError`. It never invokes GREEN while `session.red_commit_sha` is empty. `--no-judge` makes the no-failing-test outcome a hard failure (adjudication disabled). Test discovery is language-agnostic: the RED gate no longer globs Python `tests/**/test_*.py` (`_find_test_files`); the project's own convention is honored through the resolved test command (e.g. `mix test` collecting `test/**/*_test.exs` for Elixir/Phoenix), so a correctly authored non-Python test is neither rejected up front nor silently conflated with "no test framework" — a project with no resolvable test command routes to the same JUDGE adjudication instead of failing. This closes the prior stall where an empty `_find_test_files` let RED silently commit a vacuous 'failing test' and GREEN die in `TRAIN_EXHAUSTED`. The RED agent may steer the adjudication by declaring `failure_kind: already_satisfied` (behavior exists) with a non-empty `files` set and/or `test_file`, or `failure_kind: test_defect` (test wrong) with a `rationale` on its handover manifest. A passing suite with no named test files is not a COMPLETE.
 * **JUDGE / TRAIN (The Compliance Gate) — with Green → Judge → Green loop:**
-    * **The Judge:** The CLI evaluates the committed RED-parent-to-HEAD diff against `spec.md` for invariant/security violations. When `session.red_commit_sha` has advanced onto a `docs(...): add judge feedback for retry` commit, `_assemble_judge_injected_diff` calls `_resolve_judge_diff_base` to walk back to the RED-phase failing-test commit before running `git diff {red_sha}^..HEAD`, so RED tests stay visible to the evidence gate (GH-88 / GH-90). If GREEN tests failed before the implementation commit, `_run_judge_phase` also appends staged/unstaged `git diff HEAD` output and per-file `git diff --no-index /dev/null <path>` output for untracked files, so JUDGE assesses the retained implementation rather than a false RED-only snapshot. This judge operates in a clean, zero-shared-history session to break recursive subjectivity. A `deviate-judge` skill (loaded from `_SKILL_NAMES["JUDGE"]`) guides the agent through supplementary compliance evaluation. TDD JUDGE evidence is task-scoped: `_run_judge_phase` resolves required `AC-PLAN-NNN` tokens via `resolve_task_ac_tokens` (non-empty `acceptance_criteria` `criterion_id`s, else this task's `tasks.md` card minus `**Judge Feedback**` bullets and their continuation lines, else none) and does not fall back to every token in `plan.md`. TDD `_run_judge_phase` then rejects `COMPLIANCE_PASS` unless `HandoverManifest.evidence` quotes for those task tokens match the injected diff (or HEAD file contents on the already-exists `skip_refactor` edge) and every declared `files` / `test_file` path exists in that snapshot. Unmatched PASS rewrites to `revert_to_red` / `revert_before`. On a forward PASS the runner stashes those citations on `SessionState.validated_evidence` (transient only) and writes them onto the COMPLETED `tasks.jsonl` row as `TaskRecord.evidence` (`items` plus `red` / `green` / `head` SHAs) so `deviate inspect tasks show` can display the proof after the session is gone (GH-84). TDD COMPLETE with `AC-PLAN-NNN` tokens refuse when that bundle is missing or does not cover the tokens (`evaluate_judge_evidence`). `.deviate/` session files are not the proof store. Earlier RED/GREEN/JUDGE rows stay lean. Persist the judge's own `train_feedback` / `violations` when present (GH-103 citation strip still applies); attach the generic missing-evidence string only when the judge emitted none (GH-102). `_append_judge_feedback` keys the card with `_TASK_BULLET_HEAD_RE` exact-id match and inserts under that card only (does not walk past a later phase heading). Gate 3 review (`deviate review`) owns plan-wide AC coverage. EXECUTE, IMMEDIATE, and DIRECT judge paths stay ungated.
+    * **The Judge:** The CLI evaluates the committed RED-parent-to-HEAD diff against `spec.md` for invariant/security violations. When `session.red_commit_sha` has advanced onto a `docs(...): add judge feedback for retry` commit, `_assemble_judge_injected_diff` calls `_resolve_judge_diff_base` to walk back to the RED-phase failing-test commit before running `git diff {red_sha}^..HEAD`, so RED tests stay visible to the evidence gate (GH-88 / GH-90). If GREEN tests failed before the implementation commit, `_run_judge_phase` also appends staged/unstaged `git diff HEAD` output and per-file `git diff --no-index /dev/null <path>` output for untracked files, so JUDGE assesses the retained implementation rather than a false RED-only snapshot. This judge operates in a clean, zero-shared-history session to break recursive subjectivity. A `deviate-judge` skill (loaded from `_SKILL_NAMES["JUDGE"]`) guides the agent through supplementary compliance evaluation. TDD JUDGE evidence is task-scoped: `_run_judge_phase` resolves required `AC-PLAN-NNN` tokens via `resolve_task_ac_tokens` (non-empty `acceptance_criteria` `criterion_id`s, else this task's `tasks.md` card minus `**Judge Feedback**` bullets and their continuation lines, else none) and does not fall back to every token in `plan.md`. Auto `_build_auto_prompt("judge")` injects that same stripped card as `<task_card source="tasks.md">` so prior-round Judge-Feedback prose cannot bias the next judge (GH-118); `_task_card_text` remains raw. TDD `_run_judge_phase` then rejects `COMPLIANCE_PASS` unless `HandoverManifest.evidence` quotes for those task tokens match the injected diff (or HEAD file contents on the already-exists `skip_refactor` edge) and every declared `files` / `test_file` path exists in that snapshot. Unmatched PASS rewrites to `revert_to_red` / `revert_before`. On a forward PASS the runner stashes those citations on `SessionState.validated_evidence` (transient only) and writes them onto the COMPLETED `tasks.jsonl` row as `TaskRecord.evidence` (`items` plus `red` / `green` / `head` SHAs) so `deviate inspect tasks show` can display the proof after the session is gone (GH-84). TDD COMPLETE with `AC-PLAN-NNN` tokens refuse when that bundle is missing or does not cover the tokens (`evaluate_judge_evidence`). `.deviate/` session files are not the proof store. Earlier RED/GREEN/JUDGE rows stay lean. Persist the judge's own `train_feedback` / `violations` when present (GH-103 citation strip still applies); attach the generic missing-evidence string only when the judge emitted none (GH-102). `_append_judge_feedback` keys the card with `_TASK_BULLET_HEAD_RE` exact-id match and inserts under that card only (does not walk past a later phase heading). Gate 3 review (`deviate review`) owns plan-wide AC coverage. EXECUTE, IMMEDIATE, and DIRECT judge paths stay ungated.
     * **The Train (Green → Judge → Green loop):** On `COMPLIANCE_VIOLATION` or test failure, the CLI safely resets without destroying task progress. The JUDGE phase honors `HandoverManifest.next_action` (see [specs/DeviaTDD-api.md](./DeviaTDD-api.md) for the routing table). The five routes:
         1. **`revert_before`** — discard this task's GREEN **and** its RED. `_resolve_pre_red_sha()` derives the SHA from `red_commit_sha^` (defended by a subject-match regex on the parent's commit message; logs `PRE_RED_AMBIGUOUS` when the parent isn't a RED-phase convention). The pre-RED anchor is threaded into `_execute_rollback(boundary_sha=<pre_red>, task_id=<tid>, attempt=<rollback_attempts>)`; the agent's pre-reset HEAD is captured on the per-attempt recovery ref `tmp/deviate-agent-work/<sanitized-task-id>/attempt-<rollback_attempts>` so a parent SIGTERM between `git reset` and `git clean` doesn't strand the discarded commit. `session.red_commit_sha` is cleared (the boundary was discarded) and `pending_judge_action = "revert_before"`. `force_transition_to("RED")` so the task retries from scratch. `_escalate_to_new_red` consumes `revert_before` only after a RED-phase `red_commit_sha` lands. While that SHA is empty, the next `INVOKE_AGENT` stays RED (or the loop raises `TRAIN_EXHAUSTED` / `PhaseFailedError`). **No implicit fallback**: if `_resolve_pre_red_sha` returns empty AND `session.red_commit_sha` is empty, the runner raises `PhaseFailedError("ROLLBACK_BOUNDARY_MISSING ...")` rather than fall back to `HEAD~1`. When `pre_red` is unresolvable but `session.red_commit_sha` is known, that cached SHA is used as the explicit boundary.
            **Runner-level override on `failure_kind=test_defect`:** when `session.failure_kind == "test_defect"` and JUDGE emits `COMPLIANCE_VIOLATION`, `_coerce_judge_action` (`src/deviate/cli/micro.py`) forces `next_action="revert_before"` regardless of what the JUDGE manifest declared or omitted. The override reflects a contract invariant: when the RED test itself is wrong, looping back to GREEN with the same test is futile. `_run_tdd_cycle` honours the resulting `pending_judge_action == "revert_before"` by escalating now. It resets `green_attempts` to 0, increments `red_attempts`, and persists both on `.deviate/session.json`. It then dispatches `_run_red_phase(task, ..., bypass_phase_done=True)` so a fresh RED record appends to the append-only ledger (never rewriting prior entries). The retry RED prompt receives a short `previous cycle failed because …` note, not the raw GREEN dump. `TRAIN_EXHAUSTED` prints only after three RED escalates. The override is silenced on `COMPLIANCE_PASS` verdicts; JUDGE's outcome remains authoritative when the implementation is sound. The override preserves the legacy resolution for `revert_to_red`, `continue_refactor`, `proceed_to_refactor_no_diff`, and `skip_refactor` — only the test_defect case is forced.
@@ -689,7 +689,7 @@ The orchestrator must maintain and enforce these structural constraints across a
 
 2. **The Scope Audit Law:** When entering or running the `GREEN` execution phase, the system checks for unauthorized changes to test, spec, and config directories. Protected files are reverted via `git restore <filepath>`. The JUDGE phase (`deviate judge pre`) additionally performs compliance verification by detecting changes to protected modules declared in `spec.md` `Module:` lines. Complements the GREEN stub-PASS guard in `_run_green_phase` (see `DeviaTDD-api.md` § GREEN Stub-PASS Guard): scope rejects writes the agent shouldn't have made; the stub-PASS guard rejects passes the agent shouldn't have emitted.
 
-3. **Append-Only Ledger Protocol (issues.jsonl + tasks.jsonl):** All state transitions are append-only. The global `specs/issues.jsonl` serves as the authoritative issue registry. Issue-scoped micro-task ledgers live at `specs/{FEATURE_SLUG}/{ISSUE_ID}/tasks.jsonl` — the bucket directory (`{FEATURE_SLUG}`) is the epic scope (e.g. `001-…`, `002-…`, or `adhoc`); `{ISSUE_ID}` is the per-epic ordinal matching the issue markdown filename. The `source_file` recorded in `specs/issues.jsonl` follows `specs/{FEATURE_SLUG}/issues/{ISSUE_ID}.md` and the CLI strips the `issues/` segment when mapping to the tasks directory. Agents cannot edit any status fields directly — only the CLI may append events via `append_issue_transition()` and `append_task_transition()`. No existing line is ever modified or overwritten. Canonical state is derived by parsing each ledger using compound-key idempotency (bottom-up for `issues.jsonl`; `(id, status)` compound key for `tasks.jsonl`). For per-issue task ledgers, `COMPLETED` is terminal: once captured, no later non-`COMPLETED` transition may override it; among non-terminal entries, the last by file position wins. Ad-hoc issues bypass macro planning and route directly to isolated execution workspaces.
+3. **Append-Only Ledger Protocol (issues.jsonl + tasks.jsonl):** All state transitions are append-only. Append helpers (`_append_record`, `_append_with_compound_key`) insert a leading newline when a non-empty ledger does not already end in `\n`, so a missing trailing newline cannot fuse two records onto one line; every successful write leaves a trailing newline. `claim_issue` writes through `append_issue_transition`. The global `specs/issues.jsonl` serves as the authoritative issue registry. Issue-scoped micro-task ledgers live at `specs/{FEATURE_SLUG}/{ISSUE_ID}/tasks.jsonl` — the bucket directory (`{FEATURE_SLUG}`) is the epic scope (e.g. `001-…`, `002-…`, or `adhoc`); `{ISSUE_ID}` is the per-epic ordinal matching the issue markdown filename. The `source_file` recorded in `specs/issues.jsonl` follows `specs/{FEATURE_SLUG}/issues/{ISSUE_ID}.md` and the CLI strips the `issues/` segment when mapping to the tasks directory. Agents cannot edit any status fields directly — only the CLI may append events via `append_issue_transition()` and `append_task_transition()`. No existing line is ever modified or overwritten. Canonical state is derived by parsing each ledger using compound-key idempotency (bottom-up for `issues.jsonl`; `(id, status)` compound key for `tasks.jsonl`). For per-issue task ledgers, `COMPLETED` is terminal: once captured, no later non-`COMPLETED` transition may override it; among non-terminal entries, the last by file position wins. Ad-hoc issues bypass macro planning and route directly to isolated execution workspaces.
 
 4. **Deterministic Test Failure Check:** For a `RED` phase to be valid (`deviate red post`), `_classify_pytest_outcome()` must return `ASSERTION_FAILURE`. Return codes of `PASS` or `SYNTAX_ERROR` (SyntaxError, IndentationError, TabError, ImportError, ModuleNotFoundError) are rejected. Current implementation uses string-based parsing of `pytest -v` output; `pytest --json-report` migration is specified but not yet implemented.
 
@@ -704,7 +704,7 @@ The orchestrator must maintain and enforce these structural constraints across a
    composable overrides that take precedence over profile defaults. Execution
    profiles and agent backends are configured via `DeviateConfig.agent.backend`.
 
-7. **Atomic Concurrency Protocol (Git Reference Locks):** To eliminate TOCTOU race conditions across distributed terminal instances, the issue claim workflow (formerly `deviate specify pre`, now part of the Plan phase orchestration) uses try-claim semantics. `select_unblocked_candidates()` returns all available BACKLOG issues. The worker iterates through them and attempts `claim_issue()` combined with `create_worktree()`. Next `NNN` is max(origin ledger, current ledger, remote `feat/<epic>/<NNN>-*` / `feat/adhoc/<NNN>-*`) + 1. Unmerged remote feat refs feed that max. Local-only unpushed feat branches do not reserve. The default serialization is push-as-lock: `git push -u <remote> <branch>`. The server serializes concurrent pushes. The first successful push wins. When `git push` of `feat/.../NNN-*` is rejected because the name exists, the claim path increments the ordinal and retries (cap 3). Collision retry does not set `--local`. Push-as-lock is the default, not a mandatory step. Local mode (`--local` on `deviate specify`, `deviate meso run`, or `deviate run`, or `claim_remote = false` in `.deviate/config.toml`) keeps the worktree and the ledger claim and skips the remote lock. Local mode is the explicit skip. It is not a collision winner. The `tasks.jsonl` ledger records the authoritative outcome.
+7. **Atomic Concurrency Protocol (Git Reference Locks):** To eliminate TOCTOU race conditions across distributed terminal instances, the issue claim workflow (formerly `deviate specify pre`, now part of the Plan phase orchestration) uses try-claim semantics. `select_unblocked_candidates()` returns all available BACKLOG issues. The worker iterates through them and attempts `claim_issue()` combined with `create_worktree()`. `_discover_claimable_issue` skips a candidate both when its `feat/<epic>/<slug>` branch already exists on origin (claimed elsewhere) and when that branch already has a local worktree (claimed here) — the local-worktree guard is what lets two parallel terminals on the same checkout claim two different BACKLOG issues even though each claim's SPECIFIED row lives on the feature branch and stays invisible to the main checkout's ledger. Next `NNN` is max(origin ledger, current ledger, remote `feat/<epic>/<NNN>-*` / `feat/adhoc/<NNN>-*`) + 1. Unmerged remote feat refs feed that max. Local-only unpushed feat branches do not reserve. The default serialization is push-as-lock: `git push -u <remote> <branch>`. The server serializes concurrent pushes. The first successful push wins. When `git push` of `feat/.../NNN-*` is rejected because the name exists, the claim path increments the ordinal and retries (cap 3). Collision retry does not set `--local`. Push-as-lock is the default, not a mandatory step. Local mode (`--local` on `deviate specify`, `deviate meso run`, or `deviate run`, or `claim_remote = false` in `.deviate/config.toml`) keeps the worktree and the ledger claim and skips the remote lock. Local mode is the explicit skip. It is not a collision winner. The `tasks.jsonl` ledger records the authoritative outcome.
 
 8. **The Session Continuity Principle:** Session state is persisted to `.deviate/session.json` after each CLI command. The `SessionState` class tracks `current_phase`, `active_issue_id`, and `last_command`. Macro and meso phases transition through `transition_to()` with validation from `_MACRO_TRANSITION_MAP`. Micro phases use `force_transition_to()`. The `_run_single()` function checks `session.current_phase` and supports resume from JUDGE/REFACTOR via optional `start_phase` parameter. Model continuity and KV cache management are delegated to the calling environment.
 
@@ -863,7 +863,15 @@ handing the manifest to the rest of the pipeline:
    pass a recovered manifest. `HandoverManifest` is imported by
    `scripts/verify_install.py` (the post-install smoke verifier)
    which checks the new constants and the recovery behaviour.
-6. **Schema-rejection fail-fast** — the first stderr or stdout line
+6. **Unescaped evidence-quote recovery (GH-116)** — when
+   `yaml.safe_load` fails because an evidence `quote` /
+   `test_quote` / `impl_quote` double-quoted scalar embeds raw
+   `"`, `_safe_load_handover_yaml` rewrites those lines as `|`
+   block scalars and reloads. Well-formed YAML is unchanged.
+   Truly malformed YAML still raises
+   `MalformedHandoverManifestError`. Verdict and evidence
+   semantics are unchanged.
+7. **Schema-rejection fail-fast** — the first stderr or stdout line
    that contains `tool_count_limit` or `unsupported_tool_schema`
    kills the child. `invoke` raises `AgentSubprocessError` with those
    tokens. This path does not wait for the 900s stall clock. It does
@@ -879,6 +887,7 @@ handing the manifest to the rest of the pipeline:
 | `claude` | `claude -p --permission-mode auto` | Commands copied into `.claude/commands/` (flat `.md`) | `--model <id>` flag (may be ignored by host env) | Print mode, auto permission |
 | `droid` | `droid exec` | Commands copied into `.factory/commands/` (flat `.md`) | `--model <id>` flag | Factory Droid IDE-owned commands dir |
 | `pi` | `pi -p` | Commands file-copied into `<workdir>/.pi/prompts/<name>.md` (project-local; flat top-level only per Pi's documented slash-command convention) | `--model <id>` flag (accepts `provider/model` shorthand) | Lean spawn after `pi -p` / RPC `--no-session`: `--no-extensions`, `--tools read,bash,edit,write`, `--no-skills`, optional `--skill`; schema-limit tokens abort as `AGENT_ERROR` |
+| `codex` | `codex exec --sandbox workspace-write --ask-for-approval never` | Skills written to `<workdir>/.agents/skills/<name>/SKILL.md` (Codex CLI 0.117+ dropped `.codex/prompts`). Packaged `deviatdd` skill plus one skill folder per slash command. | `--model <id>` flag | CLI transport only (no Codex RPC). Prompt via stdin. Do not use `--full-auto` or `--dangerously-bypass-approvals-and-sandbox`. |
 
 Pi implements slash-command discovery natively — `pi -p` loads commands from
 `~/.pi/agent/`, `.pi/prompts/`, and `.agents/` on startup, parses the
@@ -950,18 +959,18 @@ standard `AgentBackend.invoke()` contract with these customisations:
    the tokens. This path does not wait 900s. It does not treat those
    tokens as stall liveness. EXECUTE stall stays 3600s.
 
-### 10.2.5 Project-Local `deviatdd` Skill (Single Skill, Write-Everywhere)
+### 10.2.5 Project-Local `deviatdd` Skill (Single Skill, Selected Agent)
 
 In addition to the 25 `deviate-*` slash commands under
 `<workdir>/.<agent>/commands/` and `<workdir>/.pi/prompts/`, `deviate setup`
 provisions exactly **one** project-local skill named `deviatdd` at
-`<workdir>/.<agent>/skills/deviatdd/SKILL.md` for every agent platform
-in `active_agents` (`claude`, `opencode`, `factory`, `pi`, `omp`).
-This mirrors `_install_commands_to_agents`'s write-everywhere policy:
-the skill body is identical across platforms, only the destination
-directory differs, and the write is unconditional — every operator
-using `--agent <platform>` gets the skill at the canonical skills
-directory for their platform.
+`<workdir>/.<agent>/skills/deviatdd/SKILL.md` for the selected agent
+only (`claude`, `opencode`, `factory`/`droid`, `pi`, `omp`). Codex
+receives the same skill at `<workdir>/.agents/skills/deviatdd/SKILL.md`
+plus one `.agents/skills/<command>/SKILL.md` per packaged slash command.
+`--agent` gates both command and skill install; `droid` normalizes to
+`.factory/`. The skill body is identical across platforms — only the
+destination directory differs.
 
 **Auto-discovery status per platform (informational, does not gate the
 write):**
@@ -979,6 +988,9 @@ write):**
   `~/.omp/agent/managed-skills/<name>/SKILL.md` and via a
   settings-driven `skills` array. Operators register the
   project-local file via OMP's `skills` array in settings.
+- `codex` — official project-local discovery is
+  `.agents/skills/<name>/SKILL.md`. Codex CLI 0.117+ dropped
+  `.codex/prompts` and `/prompts:`.
 
 **Source of truth:** `src/deviate/prompts/skills/deviatdd/SKILL.md`
 (package resource, loaded via `importlib.resources`).
@@ -1036,18 +1048,21 @@ field schemas live in `micro.py` itself, not duplicated here.
 **`.gitignore` exclusions:** `_ensure_root_gitignore` adds
 `*/skills/deviatdd/` to the entries tuple alongside
 `*/commands/deviate-*.md` and `*/prompts/deviate-*.md`. The
-single-level wildcard covers all five agent platforms (`.claude/`,
-`.opencode/`, `.factory/`, `.pi/`, `.omp/`) with one pattern. The
-single-level prefix (`*/`, not `**/`) is critical: it scopes the
-pattern to the project root, never matching the deviatdd project's
-own source at `src/deviate/prompts/skills/deviatdd/` (three
-directories deep).
-
-**Tests:** `TestInstallDeviatddSkill` (8 tests) in
-`tests/test_cli/test_init.py` covers install-to-all-five-agents,
-idempotence, gitignore entry presence + idempotence, the safety-gate
-fragments in the SKILL.md body, well-formed frontmatter, and the
-dispatch table's canonical slash-command references.
+single-level wildcard covers every selected-agent skill install
+(`.claude/`, `.opencode/`, `.factory/`, `.pi/`, `.omp/`, `.agents/`)
+with one pattern. `*/skills/deviate-*/` covers Codex per-command
+skill dirs. The single-level prefix (`*/`, not `**/`) is critical: it
+scopes the pattern to the project root, never matching the
+deviatdd project's own source at
+`src/deviate/prompts/skills/deviatdd/` (three directories deep).
+
+**Tests:** `TestInstallDeviatddSkill` in `tests/test_cli/test_init.py`
+and `TestSetupSelectedAgentIsolation` / `TestSetupCodex` in
+`tests/test_cli/test_setup.py` cover selected-agent-only install,
+Codex skills + `backend = "codex"`, idempotence, gitignore entry
+presence + idempotence, the safety-gate fragments in the SKILL.md
+body, well-formed frontmatter, and the dispatch table's canonical
+slash-command references.
 
 
 ### 10.3 Pi Sandbox Boundary