deviatdd 2.20.1__tar.gz → 2.20.2__tar.gz

deviatdd-2.20.2/.worktrees/work/.env.example

@@ -0,0 +1,8 @@
+# PyPI API token for `mise run publish`.
+#
+# Generate at https://pypi.org/manage/account/token/
+#   - Scope the token to the `deviatdd` project only (not account-wide)
+#   - Copy this file to `.env` and paste your real token
+#   - `.env` is gitignored; never commit secrets
+
+PYPI_API_TOKEN=

{deviatdd-2.20.1 → deviatdd-2.20.2}/CHANGELOG.md

@@ -23,6 +23,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`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`.
 ### Changed
+- **Ad-hoc issue creation no longer marks the record COMPLETED at creation time.** `/deviate-adhoc` step 7 previously instructed the agent to “mark the record as completed” via `deviate adhoc post` — but that CLI reads a different ledger (`specs/adhoc.jsonl`) than the `specs/issues.jsonl` ledger the prompt populates, so agents instead appended a raw `COMPLETED` transition to `specs/issues.jsonl` immediately, before any plan/tasks/red-green work ran (visible as instant `BACKLOG → SPECIFIED → COMPLETED` sequences for `ISS-ADH-003/004/013`). Step 7 now commits artifacts with a plain `git commit`, leaves the record at `BACKLOG`, and forbids appending any `COMPLETED` transition at creation — completion is written only by later phase post-scripts. The re-installed mirrors (`.opencode/`, `.claude/`, `.omp/`, `.factory/`) carry the fix via `deviate setup`. Prompt-only change in `src/deviate/prompts/commands/deviate-adhoc.md`; pinned by the existing `TestConsumerRepositoryPromptBoundaries` prompt tests.
+- **`/deviate-tasks` no longer waits for the removed Gate 2 approval.** The prompt still said the workflow “stops for joint human review” and that “TDD begins only after explicit artifact-bound Gate 2 approval” — but constitution 0.8.0 removed Gate 2, so the agent was being told to wait for an approval that no longer exists. The Meso Workflow Position line and the Tasks/TDD bullets now state that no human-approval gate sits between Tasks and Micro and that `deviate run` chains meso into micro end-to-end. Prompt-only change in `src/deviate/prompts/commands/deviate-tasks.md`, consistent with the constitution's Automated Advance invariant.
 - **RED phase now hard-fails when it produces no test files (`RED phase produced no test files`), instead of silently committing a vacuous 'failing test' commit.** Previously `_run_red_phase` skipped its test run entirely when `_find_test_files` returned empty, letting GREEN run against nothing and die in `TRAIN_EXHAUSTED` — a real stall. It now raises a `PhaseFailedError` naming `/deviate-execute` (DIRECT) or `/deviate-meso` re-sharding for tasks that legitimately need no code. It also treats a pytest-style exit code 5 (no tests collected) as a RED defect rather than a passing RED. The manual `deviate red post` `RedMustPassError` message now points the agent at the `failure_kind: already_satisfied` escape hatch instead of leading to an opaque crash. Pinned by the updated `_find_test_files`-mocked RED unit tests.
 - **Bare `deviate specify` now skips issues already claimed on a remote branch during auto-discovery.** Previously it auto-discovered the next unblocked BACKLOG issue via `select_next_unblocked_issue()` without checking the remote, so it could pick an issue whose `feat/{epic}/{issue}` branch already existed on `origin` (claimed elsewhere) and then hard-fail with `CLAIM_FAILED`. It now uses `_discover_claimable_issue()` — the same discovery `deviate meso run` uses — which skips issues whose branch is on the remote (or already COMPLETED) and reaches the next genuinely claimable one. When none remain it exits `NO_CLAIMABLE_ISSUES`. `deviate specify <id>` / `--local` explicit-claim behavior is unchanged. Pinned by `tests/test_meso/test_specify.py::TestSpecifySetup::test_specify_bare_arg_skips_remote_claimed_issue`.
 - **`deviate explore post` no longer writes ``FLOW_REFERENCED_BY_ISSUE`` events into ``specs/_product/flows.jsonl``.** The flows ledger never records issue-flow references — the referenced-by relationship is derived read-only at coverage time from ``specs/issues.jsonl::flow_refs`` (via ``load_flow_coverage``/``_latest_issue_reference``). `deviate explore post` (``_run_flow_ledger_cycle``) now renders the coverage report only; the macro-layer reverse-index helper ``_reverse_index_issue_flow_refs`` was removed. ``flows.jsonl`` still carries ``FLOW_DISCOVERED`` / ``FLOW_DOCUMENTED`` (from `deviate flows sync`), confirmation/evidence/release events (from merge/release), and deprecated events. Pinned by `tests/test_macro/test_explore.py::test_explore_post_never_writes_referenced_by_events`.

{deviatdd-2.20.1 → deviatdd-2.20.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: deviatdd
-Version: 2.20.1
+Version: 2.20.2
 Summary: DeviaTDD CLI — agent orchestration framework
 Project-URL: Homepage, https://github.com/wernerbisschoff/deviatdd
 Project-URL: Repository, https://github.com/wernerbisschoff/deviatdd

{deviatdd-2.20.1 → deviatdd-2.20.2}/pyproject.toml

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

deviatdd-2.20.2/specs/005-acceptance-gates/002-task-acceptance-traceability/plan.md

@@ -0,0 +1,150 @@
+# Plan — Task Acceptance Traceability via acceptance_criteria Links
+
+## Plan Summary
+
+- **Issue**: 005-002 — Task Acceptance Traceability via `acceptance_criteria` Links
+- **Implementation Strategy**: This is a re-plan: prior `plan.md` was reviewed and refreshed against the completed issue `005-001`, whose `validate_acceptance_contract` (`src/deviate/core/validation.py:162`) now enforces one `**Verification Mode**` line per `AC-PLAN-NNN` scenario. Add a `CriterionLink` Pydantic model and an optional `acceptance_criteria: list[CriterionLink] | None` field to `TaskRecord` in `src/deviate/state/ledger.py`. Extend `generate_jsonl_from_md` and `_build_task_record` in `src/deviate/core/tasks_ledger.py` to parse per-task `**Acceptance Criteria**:` bullets from `tasks.md` and propagate the parsed links into each generated row. `CriterionLink` enforces the `AC-PLAN-\d{3}` id format, the three verification-mode literals, and the automated-link `test_ref` invariant, so malformed links fail generation with named errors. The field stays optional with default `None`, so legacy rows without the field parse under `model_config = {"extra": "forbid"}`.
+- **Estimated Complexity**: Medium
+- **Estimated Effort**: 2-4 hours
+
+## Product Layer Anchors
+
+- **Flow References**: `[]`
+- **Source**: `specs/005-acceptance-gates/issues/002-task-acceptance-traceability.md` (frontmatter field: `flow_refs`)
+- **Release Context**: `specs/_product/release-next.md` Goal ships FLOW-04 (live-stream agent progress via subprocess RPC and a Rich TUI renderer capped at 10 lines). This issue is orthogonal; it hardens meso task-generation traceability, not the RPC/TUI transport.
+- **Architecture Components Touched**: `C1` (the existing `deviate` CLI component; the `## Components` table C1 entry states it owns phase state, JSONL ledgers, and TOML config, which covers `src/deviate/state/ledger.py` and `src/deviate/core/tasks_ledger.py`)
+
+## Acceptance Contract
+
+**Scenario AC-PLAN-001: Tasks.md criterion references propagate into generated task rows as acceptance_criteria links**
+- **Source Outline**: `AO-002`
+- **Upstream Traceability**: `US-005-03`, `FR-005-02`, `AC-005-02-01`
+- **Current-Code Evidence**: `src/deviate/core/tasks_ledger.py:15`
+- **Given**: a `tasks.md` whose task `TSK-005-01` carries an `**Acceptance Criteria**:` bullet that declares `AC-PLAN-001 (automated, tests/test_core/test_tasks_ledger.py)` and `AC-PLAN-002 (manual)`
+- **When**: `generate_jsonl_from_md` runs on that `tasks.md`
+- **Then**: the returned `TSK-005-01` `TaskRecord` carries an `acceptance_criteria` list whose two `CriterionLink` entries match the declared `criterion_id`, `verification_mode`, and `test_ref` values
+- **Verification Mode**: automated
+
+**Scenario AC-PLAN-002: A malformed criterion id or a missing test_ref on an automated link fails generation with a named error**
+- **Source Outline**: `AO-002`
+- **Upstream Traceability**: `US-005-03`, `FR-005-02`, `AC-005-02-01`
+- **Current-Code Evidence**: `src/deviate/core/tasks_ledger.py:45`
+- **Given**: a `tasks.md` whose task declares an `**Acceptance Criteria**:` bullet with a `criterion_id` outside the `AC-PLAN-\d{3}` pattern (for example `AC-PLAN-99`), or with an `automated` link whose `test_ref` is empty
+- **When**: `generate_jsonl_from_md` runs on that `tasks.md`
+- **Then**: generation raises a validation error whose message names the invalid `criterion_id` or the missing `test_ref`
+- **Verification Mode**: automated
+
+**Scenario AC-PLAN-003: A legacy task row without the acceptance_criteria field parses with the field absent under extra="forbid"**
+- **Source Outline**: `AO-002`
+- **Upstream Traceability**: `US-005-04`, `FR-005-02`, `AC-005-02-01`
+- **Current-Code Evidence**: `src/deviate/state/ledger.py:81`
+- **Given**: a `tasks.jsonl` row written by an older CLI version that carries `id`, `issue_id`, `description`, `status`, `execution_mode`, and `created_at` but no `acceptance_criteria` field
+- **When**: `TaskRecord.model_validate` parses that row
+- **Then**: the record parses with `acceptance_criteria` equal to `None`, and a row that carries a genuinely unknown field still fails validation
+- **Verification Mode**: automated
+
+**Scenario AC-PLAN-004: A task with no criterion references carries a null acceptance_criteria field, never an empty list**
+- **Source Outline**: `AO-002`
+- **Upstream Traceability**: `US-005-03`, `FR-005-02`, `AC-005-02-01`
+- **Current-Code Evidence**: `src/deviate/state/ledger.py:97`
+- **Given**: a `tasks.md` whose task `TSK-005-04` contains no `**Acceptance Criteria**:` bullet while a sibling task declares one
+- **When**: `generate_jsonl_from_md` runs on that `tasks.md` and serializes the returned records
+- **Then**: the record for `TSK-005-04` serializes `acceptance_criteria` as `null`, never as an empty list
+- **Verification Mode**: automated
+
+## Workstation Mapping
+
+- **`src/deviate/state/ledger.py:81-98`**: MODIFY — add the optional `acceptance_criteria: list[CriterionLink] | None = None` field to `TaskRecord`.
+  - **Current State**: `TaskRecord` (line 81) declares `id`, `issue_id`, `description`, `status` (seven-value `Literal`), `execution_mode`, `created_at`, and `security_profile`; `model_config = {"extra": "forbid"}` is at line 98. No `acceptance_criteria` field exists.
+  - **Changes Required**: Insert `acceptance_criteria: list[CriterionLink] | None = None` after the `security_profile` field, before `model_config`. Preserve `model_config = {"extra": "forbid"}` and the seven-value `status` `Literal` unchanged (PRD `RESOLVED-Q-004`).
+  - **Integration Surface**: `_build_task_record` (`src/deviate/core/tasks_ledger.py:45`) constructs the model; generated JSONL rows serialize via `append_task_record` (`src/deviate/state/ledger.py:181`); micro-phase runners parse rows via `TaskRecord.model_validate` (`src/deviate/cli/micro.py:1154,1259,1336,2524,3113,4437,4533,4806`).
+- **`src/deviate/state/ledger.py`**: ADD — the `CriterionLink` Pydantic model.
+  - **Current State**: No `CriterionLink` type exists anywhere in the ledger module; `CriterionLink` appears only in the PRD/data-model schemas.
+  - **Changes Required**: Define `CriterionLink(BaseModel)` before `TaskRecord` with `criterion_id: str`, `verification_mode: Literal["automated", "manual", "deferred"]`, `test_ref: str | None = None`, and `model_config = {"extra": "forbid"}` (the ledger-family pattern; `SecurityProfile` at line 61-78 is the precedent). Add a `field_validator("criterion_id")` that rejects values that do not match `^AC-PLAN-\d{3}$`. Add a `model_validator(mode="after")` that raises when `verification_mode == "automated"` and `test_ref is None`. The data-model schema sketch (`specs/005-acceptance-gates/data-model.md:86-96`) shows the same field validator. `re` is already imported at line 4, so no new dependency is needed.
+  - **Integration Surface**: Embedded in `TaskRecord.acceptance_criteria`; validated per-link at model construction and at row parse.
+- **`src/deviate/core/tasks_ledger.py:15`**: MODIFY — `generate_jsonl_from_md` propagates task-to-criterion and criterion-to-test links from `tasks.md` into each generated `TaskRecord`.
+  - **Current State**: The function scans task lines with `_TASK_LINE_PATTERN` (line 11), tracks `current_mode` from `**Mode**:` bullets, and appends `_build_task_record(current_id, issue_id, current_desc, current_mode)` per task. It has no awareness of criterion references.
+  - **Changes Required**: Add a `_CRITERIA_LINE_PATTERN` that matches `- **Acceptance Criteria**: <entries>` inside a task block and a `_LINK_PATTERN` that parses each comma-separated entry of the form `AC-PLAN-NNN (mode[, test_ref])`. Track `current_criteria` per task, reset on each new task line, and pass the collected entries to `_build_task_record`. The parse stays linear over the line list and adds no new dependencies (stdlib `re` only).
+  - **Integration Surface**: Consumed by `validate_tasks_jsonl` (`src/deviate/core/tasks_ledger.py:60`) and by the meso task-generation flow; the emitted rows serialize through `TaskRecord.model_dump_json`.
+- **`src/deviate/core/tasks_ledger.py:45`**: MODIFY — `_build_task_record` carries the parsed links into the record.
+  - **Current State**: The helper builds `TaskRecord(id=..., issue_id=..., description=..., status="PENDING", execution_mode=...)` and returns it; no link handling exists.
+  - **Changes Required**: Accept the collected criteria entries (default empty), parse each entry with `_LINK_PATTERN`, and construct `CriterionLink` instances. An entry that fails `_LINK_PATTERN` raises a `ValueError` that names the offending text and the task id. A `criterion_id` outside `AC-PLAN-\d{3}`, a `verification_mode` outside the three literals, or an `automated` link with a null `test_ref` raises a `pydantic.ValidationError` from the `CriterionLink` validators, with the offending id or mode in the message. Pass `None` to `TaskRecord` when no links exist so the field serializes as `null`, never as `[]`.
+  - **Integration Surface**: `generate_jsonl_from_md` calls this helper once per task; `validate_tasks_jsonl` (line 60) stays the row-level validator and needs no structural change because `TaskRecord.model_validate` now owns the new field.
+- **`src/deviate/core/tasks_ledger.py:60`**: REFERENCE — `validate_tasks_jsonl` stays the row-level validator.
+  - **Current State**: The function runs `TaskRecord.model_validate` per row and formats `Record {i}: {loc}: {msg}` errors; existing tests cover valid rows, invalid ids, missing fields, invalid status, and extra fields.
+  - **Changes Required**: None structurally. The new field flows through the existing validator because `TaskRecord` owns it; new tests assert that rows with valid links pass, rows with a malformed `criterion_id` or an `automated`-with-null-`test_ref` link produce errors whose `loc` names the link, and legacy rows pass unchanged.
+  - **Integration Surface**: Called by meso task-validation flows; error strings feed task-ledger inspection.
+- **`specs/005-acceptance-gates/002-task-acceptance-traceability/tasks.md`**: TARGET — per-task criterion references (input artifact).
+  - **Current State**: The file does not exist yet; the tasks phase authors it. The sibling slice `specs/005-acceptance-gates/001-verification-mode-metadata/tasks.md` shows the bullet convention (per-task `**Mode**:`, `**Files**:`, `**Verification**:` bullets); no `tasks.md` anywhere in `specs/` carries an `**Acceptance Criteria**:` bullet today, so this plan pins the syntax.
+  - **Changes Required**: Each task that implements or verifies an `AC-PLAN-NNN` scenario declares one `- **Acceptance Criteria**:` bullet with comma-separated entries of the form `AC-PLAN-NNN (mode[, test_ref])`, where `mode` is `automated`, `manual`, or `deferred`. An `automated` entry includes the test path as `test_ref` (for example `AC-PLAN-001 (automated, tests/test_core/test_tasks_ledger.py)`). A task with no criterion references omits the bullet.
+  - **Integration Surface**: Parsed by `generate_jsonl_from_md`; the ids name `AC-PLAN-NNN` scenarios in this plan's `## Acceptance Contract`.
+- **`deviate meso tasks pre`** (`src/deviate/cli/meso.py:939-1037`): GATE — emits the traced rows through the generation path and blocks on invalid links.
+  - **Current State**: `_tasks_pre` (line 939) validates the plan contract via `validate_acceptance_contract` at line 1004 (the 005-001 behavior, now at `src/deviate/core/validation.py:162`) and blocks on `PLAN_ACCEPTANCE_CONTRACT_INVALID` / `PLAN_ACCEPTANCE_CONTRACT_MISSING`; it does not itself rewrite rows. `_tasks_post` (line 1040) commits `tasks.md`. The meso flow consumes the generator in `src/deviate/core/tasks_ledger.py`.
+  - **Changes Required**: None in this issue. The defensive exclusion in the issue scope (`005-002` §Defensive Exclusions) forbids gate-behavior work here; gate behavior belongs to issues `005-003` and `005-004`. Invalid links fail inside `CriterionLink` construction, so any consumer of `generate_jsonl_from_md` raises before a row is appended.
+  - **Integration Surface**: The gate validates the contract whose ids `CriterionLink` references; the integration tier of this issue drives a fixture `tasks.md` through `generate_jsonl_from_md` and `validate_tasks_jsonl`, the exact code path `specs/005-acceptance-gates/data-model.md:190` documents (Flow: Acceptance Traceability, step 3).
+- **`tests/test_core/test_tasks_ledger.py`**: TARGET — extend generation tests with link propagation and rejection.
+  - **Current State**: `TestGenerateJsonlFromMd` covers basic parsing (ids, issue ids, descriptions, modes, empty files); `TestValidateTasksJsonl` covers row-level rejections including the `extra="forbid"` case.
+  - **Changes Required**: Add propagation cases (single link, multiple links, mixed modes, `manual` without `test_ref`, `automated` with `test_ref`, a task without a bullet), rejection cases (malformed `criterion_id`, `automated` link with null `test_ref`, a `verification_mode` outside the literals, an unparseable entry), and the null-never-empty-list assertion. Extend `TestValidateTasksJsonl` with a valid-links row, a malformed-link row, and a legacy row without the field.
+  - **Integration Surface**: The functions under test are the same generator and row validator the meso flow consumes.
+- **`tests/test_state/test_ledger.py`**: TARGET — extend `TaskRecord` parse tests; legacy rows without the field still parse.
+  - **Current State**: `TestTaskRecord` (line 150) covers creation, explicit status/mode, invalid status/mode, extra-field rejection, id format, empty description, and serialization round-trip; `TestAppendTaskRecord` covers append behavior.
+  - **Changes Required**: Add a round-trip test with a populated `acceptance_criteria` list, a legacy-row parse test (dict without the field yields `None`), a `CriterionLink` accept/reject set, and an `extra="forbid"` regression that a genuinely unknown field still fails. Keep append-only semantics intact (no rewrite of existing rows).
+  - **Integration Surface**: The model under test is the same `TaskRecord` the micro phase runners validate at `src/deviate/cli/micro.py:1154` and later.
+
+## Implementation Strategy
+
+- **Phase 1**: `CriterionLink` model and the additive `TaskRecord` field
+  - **Files**: `src/deviate/state/ledger.py`, `tests/test_state/test_ledger.py`
+  - **Approach**: Add `CriterionLink(BaseModel)` before `TaskRecord` with `criterion_id`, `verification_mode: Literal["automated", "manual", "deferred"]`, `test_ref: str | None = None`, and `model_config = {"extra": "forbid"}`. Add a `field_validator("criterion_id")` matching `^AC-PLAN-\d{3}$` and a `model_validator(mode="after")` rejecting an `automated` link with a null `test_ref`. Add `acceptance_criteria: list[CriterionLink] | None = None` to `TaskRecord` after `security_profile`, before `model_config`. RED writes the round-trip, legacy-parse, extra-forbid, and `CriterionLink` accept/reject tests first.
+  - **Verification**: `uv run pytest tests/test_state/test_ledger.py -v`
+- **Phase 2**: Link parsing and propagation in the generator
+  - **Files**: `src/deviate/core/tasks_ledger.py`, `tests/test_core/test_tasks_ledger.py`
+  - **Approach**: Add `_CRITERIA_LINE_PATTERN` for the `**Acceptance Criteria**:` bullet and `_LINK_PATTERN` for `AC-PLAN-NNN (mode[, test_ref])` entries. Track `current_criteria` inside `generate_jsonl_from_md`, reset per task, and pass it to `_build_task_record`. In `_build_task_record`, parse entries into `CriterionLink` instances; raise a named `ValueError` for unparseable entries and let the `CriterionLink` validators raise `pydantic.ValidationError` for malformed ids, illegal modes, and automated links without `test_ref`. Pass `None` when no links exist. RED writes the propagation and rejection tests first.
+  - **Verification**: `uv run pytest tests/test_core/test_tasks_ledger.py -v`
+- **Phase 3**: Row-validator coverage and full check bundle
+  - **Files**: `tests/test_core/test_tasks_ledger.py`, `tests/test_state/test_ledger.py`
+  - **Approach**: Extend `TestValidateTasksJsonl` with valid-link, malformed-link, and legacy-row cases so `validate_tasks_jsonl` behavior is pinned without any structural change to it. Confirm the change touches only `ledger.py`, `tasks_ledger.py`, and their tests; run the full bundle. No CLI command in the new tests hits `_run_pytest`, so no `subprocess.CompletedProcess` mock is needed and the suite stays under 30 seconds.
+  - **Verification**: `uv run pytest tests/test_core/test_tasks_ledger.py tests/test_state/test_ledger.py -v`, then `mise run check`
+
+## Data Flow Analysis
+
+1. **Input**: `tasks.md` content is read by `generate_jsonl_from_md` (`src/deviate/core/tasks_ledger.py:16` via `Path.read_text`).
+2. **Extraction**: The scanner splits the content into lines; `_TASK_LINE_PATTERN` recognizes `TSK-\d{3}-\d{2}` task bullets; per-task `**Mode**:` and `**Acceptance Criteria**:` bullets accumulate on the current task.
+3. **Transformation**: `_build_task_record` converts each `**Acceptance Criteria**:` entry into a `CriterionLink` (`criterion_id`, `verification_mode`, optional `test_ref`) and constructs the `TaskRecord`; invalid entries raise `ValueError` or `pydantic.ValidationError` before any row is produced.
+4. **Output**: `TaskRecord.model_dump_json` serializes rows that carry `acceptance_criteria` when links exist and `"acceptance_criteria": null` when they do not; `append_task_record` (`src/deviate/state/ledger.py:181`) appends rows to `specs/**/tasks.jsonl` per the append-only protocol (`specs/constitution.md` §1).
+5. **Storage and consumption**: Micro-phase runners parse rows with `TaskRecord.model_validate` (`src/deviate/cli/micro.py:1154,1259,1336,2524,3113,4437,4533,4806`); rows without the field default to `None`, so mixed-version ledgers parse fully. `_read_ledger` (`src/deviate/state/ledger.py:41`) guards malformed JSONL lines with a warning instead of a crash.
+6. **Upstream constraint**: The `AC-PLAN-NNN` ids in `tasks.md` name scenarios in the owning slice's validated plan contract (`src/deviate/core/validation.py:162` `validate_acceptance_contract`, mode-enforced by `_validate_verification_mode` at `validation.py:139`); `deviate meso tasks pre` validates that contract at `src/deviate/cli/meso.py:1004` before generation, and this issue consumes the validated contract without re-checking (defensive exclusion).
+
+## Risk Assessment
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| `extra="forbid"` rejects older JSONL rows that lack the new field | High | Medium | Declare the field optional with default `None`; pin a legacy-row parse test; the design register mirrors this as `RSK-001` (`specs/005-acceptance-gates/design.md:63`). |
+| Ambiguous or drifted `tasks.md` criterion syntax silently drops links | Medium | Medium | Pin the `**Acceptance Criteria**: AC-PLAN-NNN (mode[, test_ref])` syntax in this plan; the generator raises on unparseable entries instead of skipping them. |
+| A `criterion_id` that matches `AC-PLAN-\d{3}` but names a criterion absent from the owning plan's contract escapes generation | Medium | Low | Documented boundary: `CriterionLink` validates the id pattern only; contract-level verification belongs to issue `005-001` and the micro/gate issues `005-003`/`005-004` (issue scope §Defensive Exclusions). No plan.md cross-check is added to the generator. |
+| Generation-time error messages omit the offending link details | Low | Medium | Pydantic field/model validators pin named messages that include `criterion_id` and mode; tests assert the message substrings. |
+| FLOW_CONTEXT_UNAVAILABLE — no existing flow mapping is available | Medium | Low | Preserve empty flow references and plan the application's requested behavior without creating flow or DeviaTDD setup work. |
+
+## Security Profile
+
+Risk surfaces: file paths (reads `tasks.md` via `Path.read_text` — local read only), deserialization (`json.loads` on ledger rows in `_read_ledger`, already guarded by a try/except with a warning), and string fields (`criterion_id` and `test_ref` are plain strings; `test_ref` is never resolved or executed — existence checks are explicitly out of scope per the issue's Edge Cases).
+
+Negative tests: a row with a genuinely unknown field still fails under `extra="forbid"`; a legacy row without the field parses with `acceptance_criteria` equal to `None`; an `automated` link without a `test_ref` fails generation; a `verification_mode` outside the three literals fails generation; an unparseable `**Acceptance Criteria**:` entry fails generation with a named error; a malformed JSONL line is skipped with a warning, never a crash.
+
+Constraints: no new dependencies (stdlib `re` only); no hardcoded secrets; no changes to `src/deviate/core/validation.py`, `src/deviate/cli/micro.py`, `src/deviate/prompts/`, `specs/DeviaTDD-api.md`, `specs/DeviaTDD-architecture.md`, or `CHANGELOG.md` (defensive exclusions); no subprocess in the new tests; the full suite stays under 30 seconds.
+
+## Integration Points
+
+- **`src/deviate/cli/meso.py:1004`** (`_tasks_pre` contract gate): validates the plan `## Acceptance Contract` via `validate_acceptance_contract` (`src/deviate/core/validation.py:162`) before task generation; the `AC-PLAN-NNN` ids this issue propagates refer to that contract. No change here (gate behavior belongs to issues `005-003`/`005-004`).
+- **`src/deviate/cli/micro.py` phase runners** (`TaskRecord.model_validate` at lines 1154, 1259, 1336, 2524, 3113, 4437, 4533, 4806): parse new and legacy task rows; the additive field must not break any runner. `src/deviate/prompts/auto/red.md:64` already instructs RED to trace `{TASK_ID}` to its `AC-PLAN-NNN` references in `tasks.md`.
+- **`src/deviate/cli/inspect.py:244`**: reads `tasks.jsonl` for task inspection; rows carrying the new field render without a schema change.
+- **`src/deviate/core/validation.py:166`** (`contract_pattern`, `AC-PLAN-\d{3}`) and **`:162`** (`validate_acceptance_contract`): provide and enforce the id vocabulary `CriterionLink` references; this issue consumes the validated contract and does not modify it (defensive exclusion).
+- **`specs/005-acceptance-gates/data-model.md`** (`TaskRecord` and `CriterionLink` entity tables, lines 84-110): the authoritative schema this issue implements; `acceptance_criteria` is additive with default `None` and `CriterionLink` embeds per the relationship table (line 77).
+- **`src/deviate/prompts/commands/deviate-tasks.md:47`** and **`src/deviate/prompts/auto/tasks.md:70`**: tasks-phase prompts require every task to cite its `AC-PLAN-NNN` scenarios; the new bullet syntax aligns with that requirement (prompt-template alignment itself belongs to issue `005-005`).
+
+## Constitutional Alignment
+
+- **Architecture**: The change sits in the Meso layer (task generation carries criteria traceability into `specs/**/tasks.jsonl` rows) and feeds the Micro layer (phase runners parse the additive field). It implements the `acceptance_criteria` field and `CriterionLink` schema from `specs/005-acceptance-gates/data-model.md` and satisfies the append-only ledger protocol of `specs/constitution.md` §1 — the field is additive, and no existing JSONL line is ever modified.
+- **Testing**: pytest unit tests in `tests/test_core/test_tasks_ledger.py` and `tests/test_state/test_ledger.py`; coverage target stays at or above 80%; the new tests are pure unit tests that make no CLI and no git calls, so the full suite stays under the 30-second contract (`AGENTS.md` test-performance pointer). `mise run check` (lint, format-check, types, full suite) is the final gate.
+- **Git Isolation**: The orchestrator commits at phase boundaries; this plan's tests use only `tmp_path` fixtures and make zero branch-mutating or `git` calls, so the git-isolation invariants and the append-only ledger protocol remain intact.
+- **Product Layer**: `flow_refs` is `[]` per the issue frontmatter, mirrored verbatim in `## Product Layer Anchors`; the release Goal (FLOW-04, subprocess RPC/TUI) is orthogonal and untouched. This plan adds no Product-layer, DeviaTDD setup, skill, flow-authoring, or workflow-ledger work; it only hardens the requested application behavior (task-to-criterion and criterion-to-test traceability) that the meso generation path delivers.

deviatdd-2.20.2/specs/005-acceptance-gates/002-task-acceptance-traceability/tasks.jsonl

@@ -0,0 +1,9 @@
+{"id":"TSK-005-01","issue_id":"005-002","description":"`CriterionLink` model plus the additive `TaskRecord.acceptance_criteria` field, with model-level accept/reject tests","status":"RED","execution_mode":"TDD","created_at":"2026-08-16T09:30:50.760884Z","security_profile":null}
+{"id":"TSK-005-01","issue_id":"005-002","description":"`CriterionLink` model plus the additive `TaskRecord.acceptance_criteria` field, with model-level accept/reject tests","status":"GREEN","execution_mode":"TDD","created_at":"2026-08-16T09:41:57.012207Z","security_profile":null}
+{"id":"TSK-005-01","issue_id":"005-002","description":"`CriterionLink` model plus the additive `TaskRecord.acceptance_criteria` field, with model-level accept/reject tests","status":"JUDGE","execution_mode":"TDD","created_at":"2026-08-16T09:44:26.864774Z","security_profile":null}
+{"id":"TSK-005-01","issue_id":"005-002","description":"`CriterionLink` model plus the additive `TaskRecord.acceptance_criteria` field, with model-level accept/reject tests","status":"COMPLETED","execution_mode":"TDD","created_at":"2026-08-16T09:44:26.864774Z","security_profile":null}
+{"id":"TSK-005-02","issue_id":"005-002","description":"Criterion-link parsing and propagation inside `generate_jsonl_from_md` and `_build_task_record`","status":"RED","execution_mode":"TDD","created_at":"2026-08-16T10:45:30.117531Z","security_profile":null}
+{"id":"TSK-005-02","issue_id":"005-002","description":"Criterion-link parsing and propagation inside `generate_jsonl_from_md` and `_build_task_record`","status":"GREEN","execution_mode":"TDD","created_at":"2026-08-16T10:56:18.114404Z","security_profile":null}
+{"id":"TSK-005-02","issue_id":"005-002","description":"Criterion-link parsing and propagation inside `generate_jsonl_from_md` and `_build_task_record`","status":"JUDGE","execution_mode":"TDD","created_at":"2026-08-16T11:01:16.110814Z","security_profile":null}
+{"id":"TSK-005-02","issue_id":"005-002","description":"Criterion-link parsing and propagation inside `generate_jsonl_from_md` and `_build_task_record`","status":"COMPLETED","execution_mode":"TDD","created_at":"2026-08-16T11:13:02.162546Z","security_profile":null}
+{"id":"TSK-005-03","issue_id":"005-002","description":"Row-validator accept/reject cases for link rows plus the mixed-version append regression","status":"COMPLETED","execution_mode":"IMMEDIATE","created_at":"2026-08-16T13:06:59.617574Z","security_profile":null}

deviatdd-2.20.2/specs/005-acceptance-gates/002-task-acceptance-traceability/tasks.md

@@ -0,0 +1,113 @@
+# Implementation Tasks: feat/005-acceptance-gates/002-task-acceptance-traceability
+
+## Phase 1: CriterionLink Model and Additive TaskRecord Field
+**Goal**: `CriterionLink` exists as a pydantic model with the `AC-PLAN-\d{3}` id format, the three verification-mode literals, and the automated-link `test_ref` invariant. `TaskRecord` gains the optional `acceptance_criteria: list[CriterionLink] | None = None` field while preserving `model_config = {"extra": "forbid"}` and the seven-value `status` Literal.
+
+### Tasks
+
+- TSK-005-01: `CriterionLink` model plus the additive `TaskRecord.acceptance_criteria` field, with model-level accept/reject tests
+  - **Type**: Feature_Batch
+  - **Mode**: TDD
+  - **Test Strategy**: Sociable_Unit
+  - **Verification**: `uv run pytest tests/test_state/test_ledger.py -v`
+  - **Estimated Time**: 60 minutes
+  - **Flow References**: []
+  - **Acceptance Criteria**: AC-PLAN-002 (automated, tests/test_state/test_ledger.py), AC-PLAN-003 (automated, tests/test_state/test_ledger.py), AC-PLAN-004 (automated, tests/test_state/test_ledger.py)
+  - **Files**:
+    - `src/deviate/state/ledger.py`
+    - `tests/test_state/test_ledger.py`
+  - **Rationale**: US-005-04 requires legacy task rows without the new field to parse under `extra="forbid"`; US-005-03 requires each emitted row to carry valid links. This task owns the model layer: `CriterionLink` (new) and `TaskRecord.acceptance_criteria` (additive) in `src/deviate/state/ledger.py`, the single schema that `generate_jsonl_from_md` and the micro-phase runners (`src/deviate/cli/micro.py` `TaskRecord.model_validate` sites) share. `tests/test_state/test_ledger.py` pins AC-PLAN-003 (legacy row parses with `acceptance_criteria` equal to `None`), AC-PLAN-004 (serialization emits `null`, never `[]`), and the AC-PLAN-002 rejection half that lives at model construction (malformed `criterion_id`, `automated` without `test_ref`).
+  - **Details**:
+    - **Red**: Add `TestCriterionLink` to `tests/test_state/test_ledger.py` covering: accept a `manual` link with `test_ref` absent; accept a `deferred` link with `test_ref` absent; accept `manual` or `deferred` with `test_ref` present; reject `automated` without `test_ref` asserting the message names the missing `test_ref`; reject `criterion_id` `AC-PLAN-99` asserting the message names the id; reject `verification_mode` `soon`; reject an unknown field on the link under `extra="forbid"`. Extend `TestTaskRecord` with: the field defaults to `None` when omitted; a populated `acceptance_criteria` list round-trips through `model_dump_json` and `model_validate`; a legacy dict carrying `id`, `issue_id`, `description`, `status`, `execution_mode`, `created_at` and no `acceptance_criteria` parses with the field equal to `None`; `json.loads(record.model_dump_json())["acceptance_criteria"] is None` (never `[]`) when no links exist; a genuinely unknown field such as `unknown_field` still raises under `extra="forbid"`.
+    - **Green**: In `src/deviate/state/ledger.py`, define `CriterionLink(BaseModel)` before `TaskRecord` and after `SecurityProfile`, matching the ledger-family pattern, with `criterion_id: str`, `verification_mode: Literal["automated", "manual", "deferred"]`, `test_ref: str | None = None`, and `model_config = {"extra": "forbid"}`. Add a `field_validator("criterion_id")` that raises `ValueError(f"Invalid criterion ID format: {v}")` unless `re.match(r"^AC-PLAN-\d{3}$", v)`; `re` is already imported at ledger.py line 4. Add a `model_validator(mode="after")` that raises when `verification_mode == "automated"` and `test_ref is None`. Add `acceptance_criteria: list[CriterionLink] | None = None` to `TaskRecord` after the `security_profile` field and before `model_config`; preserve the seven-value `status` Literal and `model_config = {"extra": "forbid"}` unchanged (PRD `RESOLVED-Q-004`).
+    - **Refactor**: Follow the `SecurityProfile` precedent (lines 61-78) for the validator and config pattern. Keep the validator messages named so tests can assert message substrings. Preserve deterministic field order.
+    - **Edge Cases**: An `automated` link with `test_ref=""` fails — treat the empty string as missing. A `manual` or `deferred` link with `test_ref` present passes. Extra fields on the link or on the record fail under `extra="forbid"`.
+    - **Acceptance**: `uv run pytest tests/test_state/test_ledger.py -v` passes. Rows generated by later phases serialize `"acceptance_criteria": null` when a task declares no links, and a populated list otherwise.
+
+## Phase 2: Link Parsing and Propagation in the Generator
+**Goal**: `generate_jsonl_from_md` reads per-task `- **Acceptance Criteria**:` bullets from `tasks.md`, parses each `AC-PLAN-NNN (mode[, test_ref])` entry, and emits every generated `TaskRecord` with its `acceptance_criteria` links. Malformed entries, illegal modes, and `automated` links without `test_ref` fail generation with named errors.
+
+### Tasks
+
+- TSK-005-02: Criterion-link parsing and propagation inside `generate_jsonl_from_md` and `_build_task_record`
+  - **Type**: Feature_Batch
+  - **Mode**: TDD
+  - **Test Strategy**: Sociable_Unit
+  - **Verification**: `uv run pytest tests/test_core/test_tasks_ledger.py -v`
+  - **Estimated Time**: 90 minutes
+  - **Flow References**: []
+  - **Acceptance Criteria**: AC-PLAN-001 (automated, tests/test_core/test_tasks_ledger.py), AC-PLAN-002 (automated, tests/test_core/test_tasks_ledger.py), AC-PLAN-004 (automated, tests/test_core/test_tasks_ledger.py)
+  - **Dependency**: TSK-005-01
+  - **Files**:
+    - `src/deviate/core/tasks_ledger.py`
+    - `tests/test_core/test_tasks_ledger.py`
+  - **Rationale**: US-005-03 requires the generator to emit each task row with its `acceptance_criteria` links so the task points at the criteria it satisfies and the tests that verify them. AC-PLAN-001 pins the propagation (its Given names task `TSK-005-01` carrying two links, which is this slice's own first task), AC-PLAN-002 pins generation-time rejection of malformed `criterion_id` values and of `automated` links with a missing `test_ref`, and AC-PLAN-004 pins the null-never-empty-list behavior at the generation boundary. `src/deviate/core/tasks_ledger.py` is the generator that `deviate meso tasks pre` and `validate_tasks_jsonl` consume; `tests/test_core/test_tasks_ledger.py` is its unit-level contract.
+  - **Details**:
+    - **Red**: In `tests/test_core/test_tasks_ledger.py`, extend `TestGenerateJsonlFromMd` with `tmp_path` fixtures. Propagation: a task line followed by `- **Acceptance Criteria**: AC-PLAN-001 (automated, tests/test_core/test_tasks_ledger.py), AC-PLAN-002 (manual)` yields a record whose `acceptance_criteria` list holds two `CriterionLink` entries matching the declared `criterion_id`, `verification_mode`, and `test_ref` values, with `test_ref` equal to `None` for the `manual` entry. Null-never-empty: a sibling task with no bullet carries `acceptance_criteria is None`. Rejection: `AC-PLAN-99 (automated, tests/test_core/test_tasks_ledger.py)` raises with the invalid id named; `AC-PLAN-001 (automated)` without `test_ref` raises with the missing `test_ref` named; `AC-PLAN-001 (soon)` raises; an unparseable entry such as `AC-PLAN-001 automated` raises a `ValueError` that names the offending text and the task id. Assert the propagated ids reference `AC-PLAN-NNN` scenarios from this plan's `## Acceptance Contract`.
+    - **Green**: In `src/deviate/core/tasks_ledger.py`, add `_CRITERIA_LINE_PATTERN` matching `- **Acceptance Criteria**: <entries>` within a task block and `_LINK_PATTERN` matching `AC-PLAN-\d{3} \((automated|manual|deferred)(?:,\s*(\S+))?\)`. Track `current_criteria: list[str]` in `generate_jsonl_from_md`, reset it to `[]` on each new `_TASK_LINE_PATTERN` match, accumulate the entries text on a criteria-line match, and pass the collected entries to `_build_task_record` at both append sites (line 27 and line 39). In `_build_task_record`, accept the criteria entries (default empty), split them on top-level commas — commas inside the parenthesized entry must not split — and construct `CriterionLink` instances per entry; a fragment that fails `_LINK_PATTERN` raises `ValueError` naming the fragment and the task id; malformed ids, illegal modes, and `automated` links with a null `test_ref` raise `pydantic.ValidationError` from the `CriterionLink` validators. Pass `None` to `TaskRecord` when no links exist so the field serializes as `null`, never as `[]`. Add no new dependencies (stdlib `re` only).
+    - **Refactor**: Keep the scan linear over the line list exactly as today. Reuse the existing `current_id` / `current_desc` / `current_mode` accumulation pattern for `current_criteria`.
+    - **Edge Cases**: A criteria bullet that appears before the task's `**Mode**:` bullet still attaches to the current task. An `automated` entry with an empty `test_ref` (`AC-PLAN-001 (automated, )`) fails. `manual` and `deferred` entries with `test_ref` present pass. Whitespace around ids and modes is tolerated by the pattern. A `criterion_id` that matches `AC-PLAN-\d{3}` but names a criterion absent from the owning plan's contract is a documented boundary — no plan.md cross-check is added here (defensive exclusion).
+    - **Acceptance**: `uv run pytest tests/test_core/test_tasks_ledger.py -v` passes. Generation error messages name the invalid `criterion_id` or the missing `test_ref`. A row with links serializes `"acceptance_criteria": [{"criterion_id": ..., "verification_mode": ..., "test_ref": ...}]`.
+
+## Phase 3: Row-Validator Coverage and Full Check Bundle
+**Goal**: `validate_tasks_jsonl` behavior with link rows is pinned with no structural change to it, mixed-version ledgers append and parse intact, and the full check bundle exits green.
+
+### Tasks
+
+- TSK-005-03: Row-validator accept/reject cases for link rows plus the mixed-version append regression
+  - **Type**: Verification_Batch
+  - **Mode**: IMMEDIATE
+  - **Test Strategy**: Sociable_Unit
+  - **Verification**: `uv run pytest tests/test_core/test_tasks_ledger.py tests/test_state/test_ledger.py -v` then `mise run check`
+  - **Estimated Time**: 60 minutes
+  - **Flow References**: []
+  - **Acceptance Criteria**: AC-PLAN-001 (automated, tests/test_core/test_tasks_ledger.py), AC-PLAN-002 (automated, tests/test_core/test_tasks_ledger.py), AC-PLAN-003 (automated, tests/test_state/test_ledger.py)
+  - **Dependency**: TSK-005-02
+  - **Files**:
+    - `tests/test_core/test_tasks_ledger.py`
+    - `tests/test_state/test_ledger.py`
+  - **Rationale**: US-005-03 and US-005-04 both terminate in the row-level validator and ledger consumption. `validate_tasks_jsonl` (`src/deviate/core/tasks_ledger.py:60`) stays structurally unchanged — `TaskRecord.model_validate` owns the new field — but its behavior with link rows must be pinned so mixed-version ledgers never break the micro-phase runners. AC-PLAN-001 (a row with valid links passes), AC-PLAN-002 (a row whose link is malformed produces an error whose `loc` names the link), AC-PLAN-003 (a legacy row without the field passes). `tests/test_state/test_ledger.py` receives the mixed-version append case proving append-only semantics with the new field.
+  - **Details**:
+    - **Red**: Extend `TestValidateTasksJsonl` in `tests/test_core/test_tasks_ledger.py`: a row with a valid `acceptance_criteria` list passes with `errors == []`; a row whose link carries `criterion_id: "AC-PLAN-99"` returns an error whose `loc` names `acceptance_criteria`; a row whose `automated` link lacks `test_ref` returns an error naming `acceptance_criteria`; a legacy row without the field passes; a row that carries `acceptance_criteria` plus a genuinely unknown field still fails. In `tests/test_state/test_ledger.py`, extend `TestAppendTaskRecord`: append a legacy task row, then append a task record carrying links, then read the file back — both rows are present and unchanged, each line is appended (append-only protocol, constitution §1), and each parsed row carries the field respectively as `None` and as the populated list.
+    - **Green**: No production change. `CriterionLink` (TSK-005-01) and the generator (TSK-005-02) already produce the rows these tests exercise; `validate_tasks_jsonl` and `append_task_record` pass them through. Run the new tests against the committed implementation and confirm `git status` shows no modification to `src/deviate/cli/meso.py` or `src/deviate/core/validation.py`.
+    - **Refactor**: Reuse the dict-based record style of the existing `TestValidateTasksJsonl` cases. Keep fixture records minimal. Assert on `loc` substrings rather than full message text.
+    - **Edge Cases**: A malformed JSONL line in the append-read path is skipped with a warning, never a crash (existing `_read_ledger` guard). Mixed-version rows parse fully with the field present or absent. The append stays idempotent on the `(id, status)` compound key.
+    - **Acceptance**: `uv run pytest tests/test_core/test_tasks_ledger.py tests/test_state/test_ledger.py -v` passes, then `mise run check` (lint, format-check, types, full suite) exits 0. The complete diff touches only `src/deviate/state/ledger.py`, `src/deviate/core/tasks_ledger.py`, `tests/test_core/test_tasks_ledger.py`, and `tests/test_state/test_ledger.py`.
+
+---
+
+## Implementation Strategy
+**Execution Order**:
+1. Phase 1 -> Phase 2 -> Phase 3 (logical dependency order)
+
+**Critical Dependency Chains**:
+- TSK-005-01 must precede TSK-005-02 (`_build_task_record` constructs `CriterionLink` instances and sets `TaskRecord.acceptance_criteria`, both defined by TSK-005-01 in `src/deviate/state/ledger.py`)
+- TSK-005-02 must precede TSK-005-03 (TSK-005-03 pins row-validator behavior that exists only after the model field and the generator propagation land)
+
+**Risk Hotspots**:
+- `extra="forbid"` rejects older JSONL rows that lack the new field. The field is optional with default `None`, and a legacy-row parse test pins the behavior; the design register mirrors this as `RSK-001` (`specs/005-acceptance-gates/design.md:63`).
+- Ambiguous or drifted `tasks.md` criterion syntax silently drops links. The `**Acceptance Criteria**: AC-PLAN-NNN (mode[, test_ref])` syntax is pinned in this plan, and the generator raises on unparseable entries instead of skipping them.
+- `_LINK_PATTERN` entry splitting must respect parentheses: the `test_ref` comma sits inside `(...)`, so splitting the bullet on bare commas would break entries.
+- A `criterion_id` that matches `AC-PLAN-\d{3}` but names a criterion absent from the owning plan's contract escapes generation by design; contract-level verification belongs to issues `005-001`, `005-003`, and `005-004` (issue scope Defensive Exclusions).
+
+**Merge Conflict Boundaries**:
+- `tests/test_core/test_tasks_ledger.py` is touched by TSK-005-02 (extends `TestGenerateJsonlFromMd`) and TSK-005-03 (extends `TestValidateTasksJsonl`). The edits target different classes; the tasks run sequentially.
+- `tests/test_state/test_ledger.py` is touched by TSK-005-01 (adds `TestCriterionLink`, extends `TestTaskRecord`) and TSK-005-03 (extends `TestAppendTaskRecord`). The edits do not overlap.
+- `src/deviate/state/ledger.py` is touched only by TSK-005-01.
+
+**Product-Layer Anchors** (mirrored from plan.md):
+- **Flow References**: `[]`
+- **Source**: `specs/005-acceptance-gates/002-task-acceptance-traceability/plan.md`
+- Downstream micro phases inherit this list per-task. Empty references mean no matching existing flow, not permission for enabling, setup, tooling, skill, release, or workflow-ledger tasks.
+
+---
+
+## Universal Test Constraints (ALL TASKS)
+
+- **Git Isolation Mandatory**: Any test that invokes git operations MUST operate on a temporary directory initialized as a fresh git repo. Tests MUST NOT run git commands within the real repository's working tree.
+- **Implementation Pattern**: Use a shared `tmp_git_repo` fixture from `tests/conftest.py`. Pass `repo=tmp_git_repo` to all git-interacting functions. Never reference `Path.cwd()` or the real repo root.
+- **Rationale**: Prevent accidental commits, branch creation, or state mutation in the actual project repo during test execution.
+
+## Universal API Design Constraint (ALL CORE MODULES)
+
+Every git-interacting function in core modules MUST accept an optional `repo_path: Path | None = None` parameter. When `None`, default to `Path.cwd()`.

deviatdd-2.20.2/specs/adhoc/issues/016-single-source-prompt-templates.md

@@ -0,0 +1,139 @@
+---
+title: "Single-Source Prompt Templates — Auto Canonical, Manual Derived at Install"
+labels: [refactor, adhoc, vertical-slice, prompts, single-source]
+blocked_by: []
+coordinates_with: ["ISS-ADH-013"]
+issue_id: ISS-ADH-016
+flow_refs: []
+---
+
+## System Topology Mapping
+
+- **Epic Target Domain**: `specs/adhoc/`
+- **Local Issue File**: `specs/adhoc/issues/016-single-source-prompt-templates.md`
+- **Primary Architectural Workstations**:
+  - `src/deviate/prompts/assembly.py:48-107` — TARGET: `load_template` composes the auto prompt from `core/core.md` + `core/{layer}-shared.md` + `core/lifecycle-auto.md` + `core/style-ste.md` + `auto/{phase}.md`. The canonical per-phase body already lives in `auto/`; `load_template` is the auto derivation path and must keep emitting the core body only.
+  - `src/deviate/core/commands.py:55-133` — TARGET: `compose_command_body` prepends core/layer/lifecycle-manual/style to a manual command body. This is the manual derivation path. Rewire so the manual slash-command body is derived from the canonical `auto/{phase}.md` + a per-phase manual overlay instead of a hand-maintained duplicate file.
+  - `src/deviate/core/commands.py:189-243` — TARGET: `install_command` reads `commands/deviate-{phase}.md` source, composes, and writes to the agent command dir. Must instead read the canonical `auto/{phase}.md` and derive the manual body.
+  - `src/deviate/prompts/auto/{red,green,refactor,judge,execute,plan,tasks,explore,research,prd,shard}.md` — CANONICAL SOURCE: the 11 overlapping phase bodies. These hold the single source of truth; reconcile the drifted middle to the auto semantics.
+  - `src/deviate/prompts/commands/deviate-{red,green,refactor,judge,execute,plan,tasks,explore,research,prd,shard}.md` — STALE DUPLICATES: hand-maintained manual copies that drift from auto (17-68% identical-line rate). Their manual-only content (pre/post-script steps, rich handover manifest, `<context><user_input>`) becomes a derivation overlay; the duplicated middle body is removed from these files.
+  - `src/deviate/prompts/core/lifecycle-auto.md` — REFERENCE: the auto lifecycle block ("orchestrator handles all lifecycle").
+  - `src/deviate/prompts/core/lifecycle-manual.md` — REFERENCE: the manual lifecycle block ("run `deviate <phase> pre/post`").
+  - `tests/test_meso/test_auto_prompt_templates.py` — TARGET: pin canonical auto semantics; add drift-guard coverage.
+  - `tests/test_meso/test_prompt_assembly.py` — TARGET: verify auto composition still emits core only.
+  - `tests/test_core/test_commands.py` — TARGET: rework `install_command`/`compose_command_body` assertions to the derived-manual output; add a drift-guard asserting the derived manual equals the committed behavior and the middle stays identical across modes.
+  - `CHANGELOG.md` — TARGET: append a bullet under `[Unreleased]` for the user-visible template-derivation change.
+  - `specs/DeviaTDD-api.md`, `specs/DeviaTDD-architecture.md` — TARGET: reflect the single-source prompt architecture and the derivation mechanism (spec-alignment mandate).
+- **Upstream Evidence**:
+  - Git `420f65f` (2026-08-18) — redesigned auto/red only: `status:"PASS"` + `failure_kind` discriminator routed to JUDGE; the manual `status:"FAIL"` never back-ported. Proves auto is the living behavior.
+  - Git `64f9957` — per-epic issue-id change landed on `deviate-shard.md` only; auto/shard retained global ISS-NNN.
+  - `src/deviate/cli/micro.py:211` — RED task state sourced from `tasks.jsonl` (`status == "PENDING"`), confirming ledger-authoritative wording.
+  - `src/deviate/cli/meso.py:938`, `src/deviate/core/validation.py:260` — task-id validator enforces `TSK-\d{3}-\d{2}`, confirming the auto format over the manual's `T001`.
+  - `src/deviate/prompts/commands/deviate-red.md` vs `src/deviate/prompts/auto/red.md` — representative pair showing the drift.
+
+## The Problem Contract
+
+DeviaTDD maintains two parallel prompt copies per phase (`auto/<phase>.md` for the CLI-orchestrated micro runner, `commands/deviate-<phase>.md` for manual slash commands). A drift audit found the copies disagree on 17%-68% of lines, including contradictory handover manifests (RED `status:"PASS"` vs `status:"FAIL"`) and contradictory role instructions (GREEN "write only production code" vs "maintain existing functional signatures"). The intended design is a shared middle body with only start/end lifecycle differing, but the copies have diverged badly because contributors edit both by hand. The micro runner is the only path the operator runs (manual phases are long-unused), so **auto is the living behavior**. This issue makes `auto/<phase>.md` the single canonical body, derives the manual slash-command from it at install time, reconciles the drifted middle to auto semantics, deletes the duplicated manual bodies, and adds a drift guard so the middle can never diverge again.
+
+## Scope Boundaries
+
+### Hard Inclusions
+- **Auto is canonical** for all 11 overlapping phases. Reconcile each pair's drifted middle to the auto semantics. GREEN role language resolves to auto: "write ONLY production code (minimal change so that RED works)" — not "maintain existing functional signatures".
+- Rewire `install_command`/`compose_command_body` so the manual slash-command body is derived from `auto/{phase}.md` + a per-phase manual overlay (pre/post-script lifecycle steps, rich handover manifest, `<context><user_input>` block), not from a hand-maintained duplicate.
+- `load_template` keeps emitting the auto core body only (unchanged middle).
+- Delete the 11 duplicated middle bodies from `commands/deviate-{phase}.md` (the overlapping set). Retain only the frontmatter + manual overlay, or remove the files if the overlay lives elsewhere.
+- Add a drift-guard test asserting: (a) the derived manual command equals the committed manual behavior, and (b) the shared middle body is identical between auto and manual composition.
+- Update `specs/DeviaTDD-api.md` and `specs/DeviaTDD-architecture.md` in the same commit (spec-alignment mandate).
+- Append a `CHANGELOG.md` `[Unreleased]` bullet for the user-visible template-derivation change.
+
+### Defensive Exclusions
+- Do NOT change the 15 commands-only prompts (adhoc, architecture, constitution, e2e, flows, hotfix, html, init, merge, pr, prune, release, review, triage, walkthrough). They have no auto counterpart and stay hand-maintained.
+- Do NOT change the micro-runner behavior in `src/deviate/cli/micro.py` — the runner already consumes `auto/` templates.
+- Do NOT modify `core/{layer}-shared.md`, `core/core.md`, or `core/style-ste.md` shared preambles.
+- Do NOT regenerate `specs/_product/` flow artifacts; `flow_refs: []` (no existing flow covers prompt templating).
+- Do NOT touch `~/.config/opencode/skills/` or any consumer-installed command directory (read-only install mirrors).
+- Do NOT upgrade the product/governance command bodies or Graphite integration.
+- Do NOT add tests that invoke `deviate.cli.micro._run_pytest` without mocking it (AGENTS.md test-performance mandate).
+- Do NOT add `prompt`- or LLM-backed content generation during derivation — the manual overlay is static text, deterministic string composition only.
+
+## Upstream Requirement Tracing
+
+- **Requirements Tokens**: `FR-ADHOC-016`
+- **Acceptance Criteria Tokens**: `AC-ADHOC-016-01` through `AC-ADHOC-016-04`
+- **Data Model Entities**: none (no new persistent ledger models)
+- **Spec Source Anchors**:
+  - `specs/constitution.md:10` — Append-Only Ledger Protocol (unaffected)
+  - `src/deviate/cli/micro.py:211` — RED task state sourced from `tasks.jsonl`
+  - `src/deviate/cli/meso.py:938`, `src/deviate/core/validation.py:260` — `TSK-\d{3}-\d{2}` task-id validator
+
+## User Stories Ledger
+
+- **US-016-01**: As a DeviaTDD maintainer, I want a single canonical per-phase prompt body (auto) with the manual slash-command derived at install time, so I edit the middle body once instead of maintaining two drift-prone copies. *(Ref: FR-ADHOC-016)*
+- **US-016-02**: As a DeviaTDD maintainer, I want the drifted middle reconciled to auto semantics (including GREEN "write only production code" and the PASS/failure_kind RED handover), so both modes no longer instruct contradictory behavior. *(Ref: FR-ADHOC-016)*
+- **US-016-03**: As a DeviaTDD maintainer, I want a drift-guard test that fails when the auto and manual middle bodies diverge, so the identical-middle invariant is enforced rather than trusted. *(Ref: FR-ADHOC-016)*
+
+## Acceptance Outline
+
+- **AO-016** *(Ref: AC-ADHOC-016-01, US-016-01)*: For every one of the 11 overlapping phases, `install_command` derives the manual slash-command body from `auto/{phase}.md` plus the manual overlay, with a middle body identical to the auto core.
+  - **Happy Path**: `deviate setup` produces a `deviate-{phase}.md` whose middle (role, mandates, execution steps, edge cases) matches `auto/{phase}.md`; only the lifecycle start/end (pre/post scripts), the contract-input substitution, and the rich handover manifest differ.
+  - **Error Category**: A phase pair whose middle diverges fails the drift-guard test with a diff.
+  - **Boundary Category**: The derivation composes static text deterministically; no LLM or `prompt` content generation.
+- **AO-016** *(Ref: AC-ADHOC-016-02)*: The drifted middle is reconciled to auto semantics.
+  - **Happy Path**: RED manual no longer states `status:"FAIL"`/abort-on-passing-test; it matches auto's `status:"PASS"` + `failure_kind`. GREEN manual matches auto's "write only production code".
+  - **Error Category**: Any residual contradictory role instruction or handover status fails review.
+- **AO-016** *(Ref: AC-ADHOC-016-03)*: The drift-guard test exists and fails on divergence.
+  - **Happy Path**: Adding an unrelated line to an auto middle body makes the drift-guard test fail until the manual derivation is updated.
+  - **Boundary Category**: The 15 commands-only prompts are exempt from the identical-middle invariant.
+
+## Edge Cases and Boundaries
+
+- **Manual-only phase steps**: The manual overlay (pre/post-script, rich manifest, `<context><user_input>`) must live outside the shared middle so it does not leak into the auto core.
+- **Meso/macro structural divergence**: plan/tasks use `<step>` structure in auto but numbered steps in manual; research manual has `reduce_phase`/`interactive_hitl_gate_1`/`constitution_bootstrap`/`html_artifact` steps auto lacks. Reconcile per-phase before deriving — do not uniform-inject.
+- **Field-name drift**: plan auto `{plan_path}` vs manual `plan_target`; tasks auto `TSK-{NNN}-{NN}` vs manual `T001`. Resolve to the runner-enforced format (`TSK-\d{3}-\d{2}` per `meso.py:938`).
+- **Command-only frontmatter**: the manual files carry `name`/`description`/`layer` frontmatter the auto files lack. Preserve frontmatter in the derived manual output.
+- **Idempotent install**: `install_command` must return `False` when the on-disk derived command already matches, preserving the existing idempotency contract (`test_install...` graphite suite).
+- **Greenfield constitution absence**: derivation must tolerate a missing `specs/constitution.md` exactly as today (non-fatal).
+
+## Performance Constraints
+
+- **L_max (`deviate setup` install)**: ≤ 500ms above existing `deviate setup` init (matches AGENTS.md L_max ≤ 500ms init gate). Derivation is deterministic string composition — no I/O beyond reading the canonical template and writing the derived command.
+- **Full test suite**: `mise run test` remains < 30s per AGENTS.md performance mandate. New drift-guard test must read the two source files + invoke `install_command` against a `tmp_path` (no `_run_pytest`).
+- **File size impact**: net reduction — the 11 duplicated middle bodies (each 5-30KB) shrink to overlays.
+
+## Multi-Tiered Verification Targets
+
+- **Unit Sandbox Targets**:
+  - `tests/test_core/test_commands.py` — rework `install_command`/`compose_command_body` tests to assert the *derived* manual output (middle equals auto core + overlay), and that the on-disk idempotency contract (`False` on unchanged reinstall) still holds.
+  - `tests/test_meso/test_auto_prompt_templates.py` — extend with: `test_auto_and_manual_middle_identical` (drift guard) asserting the shared middle body is byte-identical between the auto core and the derived manual; `test_auto_red_uses_pass_failure_kind` asserting auto red's `failure_kind` semantics; `test_manual_red_matches_auto_semantics` asserting the derived red no longer emits `status:"FAIL"`/abort-on-passing-test.
+  - `tests/test_meso/test_prompt_assembly.py` — verify `load_template` still emits the auto core body only (core + layer + lifecycle-auto + style + phase), no manual overlay leakage.
+- **Integration Sandbox Targets**:
+  - `tests/cli/test_setup.py` (if present) — verify `deviate setup` installs a derived `deviate-red.md` matching the expected composed body.
+  - `tests/e2e/` (bats) — optional smoke test: run install, assert derived manual middle equals auto core.
+
+## Demonstration Path
+```bash
+# 1. Run the drift audit on the current pair (before migration requires auto canonical)
+diff <(tr -s ' \n' < src/deviate/prompts/auto/red.md) \
+     <(sed '1,/^---$/d' src/deviate/prompts/commands/deviate-red.md | tr -s ' \n') | head
+
+# 2. After wiring, prove the derived manual middle equals the auto core
+uv run python -c "
+from deviate.core.commands import install_command
+import tempfile, pathlib
+d = tempfile.mkdtemp()
+install_command('deviate-red', pathlib.Path(d))
+print((pathlib.Path(d)/'deviate-red.md').exists())
+"
+
+# 3. Run the drift-guard and loader tests
+mise run test tests/test_core/test_commands.py -v
+mise run test tests/test_meso/test_auto_prompt_templates.py -v
+mise run test tests/test_meso/test_prompt_assembly.py -v
+
+# 4. Lint and format
+mise run lint
+mise run format-check
+
+# 5. Full suite
+mise run test
+```

{deviatdd-2.20.1 → deviatdd-2.20.2}/specs/adhoc/prd.md

@@ -248,3 +248,19 @@
 6. AC-NARROW-06 / AO-015-06: Pydantic `FlowEvent.model_validate` rejects `FLOW_DEPRECATED` and `FLOW_IMPLEMENTATION_EVIDENCE_ADDED` event types.
 7. AC-NARROW-07 / AO-015-07: `_derive_impl_status` returns only `"CONFIRMED_IMPLEMENTED"` or `"UNCONFIRMED"`; `PARTIALLY_IMPLEMENTED` branch removed.
 8. AC-NARROW-08 / AO-015-08: Full test suite (`mise run test`), lint (`mise run lint`), format check (`mise run format-check`), and type check (`mise run check-types`) all exit 0.
+
+## FR-ADHOC-016: Single-Source Prompt Templates — Auto Canonical, Manual Derived at Install
+
+- **Description**: Make `src/deviate/prompts/auto/<phase>.md` the single canonical per-phase prompt body for the 11 overlapping phases (red, green, refactor, judge, execute, plan, tasks, explore, research, prd, shard). Derive the manual slash-command (`commands/deviate-<phase>.md`) from the auto core plus a per-phase manual overlay (pre/post-script lifecycle, contract-input substitution, rich handover manifest) at `install_command` time. Reconcile the drifted middle to auto semantics (GREEN "write only production code"; RED `status:"PASS"` + `failure_kind`). Delete the duplicated manual middle bodies. Add a drift-guard test enforcing the identical-middle invariant.
+- **Preconditions**: `src/deviate/prompts/assembly.py:48-107` (`load_template`) composes the auto prompt. `src/deviate/core/commands.py:55-133,189-243` (`compose_command_body`, `install_command`) compose and install manual slash-commands. The 11 overlapping phase pairs under `src/deviate/prompts/auto/` and `commands/` share 17-68% identical lines and contradict each other (RED `status:"PASS"` vs `"FAIL"`; GREEN role language). The micro runner (`src/deviate/cli/micro.py`) is the only actively used path and consumes `auto/` templates.
+- **Inputs/Outputs**: Input — the 11 auto phase bodies (canonical), the 11 stale manual command bodies, the shared core/lifecycle blocks, the manual overlay content. Output — a single-source `auto/<phase>.md` per phase, a derived manual command at install, the 11 duplicated manual middles removed, a drift-guard test, and updated `specs/DeviaTDD-api.md` / `specs/DeviaTDD-architecture.md`.
+- **Flow Refs**: `[]`
+- **User Stories**:
+1. US-016-01: As a DeviaTDD maintainer, I want a single canonical per-phase prompt body so I edit the middle once instead of maintaining two drift-prone copies. *(Ref: FR-ADHOC-016)*
+2. US-016-02: As a DeviaTDD maintainer, I want the drifted middle reconciled to auto semantics so both modes stop instructing contradictory behavior. *(Ref: FR-ADHOC-016)*
+3. US-016-03: As a DeviaTDD maintainer, I want a drift-guard test that fails when auto and manual middles diverge so the identical-middle invariant is enforced. *(Ref: FR-ADHOC-016)*
+- **Acceptance Outline** (implementation-independent; final Gherkin owned by `/deviate-plan`):
+1. AC-ADHOC-016-01 / AO-016-01: For each of the 11 overlapping phases, `install_command` derives the manual slash-command body from `auto/<phase>.md` plus the manual overlay; the middle is identical to the auto core.
+2. AC-ADHOC-016-02 / AO-016-02: The drifted middle is reconciled to auto semantics; RED manual no longer emits `status:"FAIL"`/abort-on-passing-test, and GREEN manual matches "write only production code".
+3. AC-ADHOC-016-03 / AO-016-03: A drift-guard test fails when an auto middle body diverges from the derived manual middle.
+4. AC-ADHOC-016-04 / AO-016-04: The 15 commands-only prompts (no auto counterpart) are unchanged; `specs/DeviaTDD-api.md` and `specs/DeviaTDD-architecture.md` are updated in the same commit; CHANGELOG gains an `[Unreleased]` bullet.

{deviatdd-2.20.1 → deviatdd-2.20.2}/specs/issues.jsonl

@@ -68,3 +68,6 @@
 {"issue_id":"005-005","type":"feature","title":"Prompt Template and Specification Alignment","status":"BACKLOG","source_file":"specs/005-acceptance-gates/issues/005-prompt-spec-alignment.md","blocked_by":["005-004"],"coordinates_with":["005-003"],"timestamp":"2026-08-14T12:28:47.899927Z","created_at":"2026-08-14T12:28:47.899930Z","flow_refs":[]}
 {"issue_id":"005-001","type":"feature","title":"Acceptance Contract Verification-Mode Metadata","status":"SPECIFIED","source_file":"specs/005-acceptance-gates/issues/001-verification-mode-metadata.md","blocked_by":[],"coordinates_with":[],"timestamp":"2026-08-14T12:30:53.080655Z","created_at":"2026-08-14T12:28:47.895924Z","flow_refs":[]}
 {"issue_id":"005-001","type":"feature","title":"Acceptance Contract Verification-Mode Metadata","status":"COMPLETED","source_file":"specs/005-acceptance-gates/issues/001-verification-mode-metadata.md","blocked_by":[],"coordinates_with":[],"timestamp":"2026-08-16T08:30:18.539420Z","created_at":"2026-08-14T12:28:47.895924Z","flow_refs":[]}
+{"issue_id":"005-002","type":"feature","title":"Task Acceptance Traceability via acceptance_criteria Links","status":"SPECIFIED","source_file":"specs/005-acceptance-gates/issues/002-task-acceptance-traceability.md","blocked_by":["005-001"],"coordinates_with":["005-001"],"timestamp":"2026-08-16T08:45:53.295510Z","created_at":"2026-08-14T12:28:47.898898Z","flow_refs":[]}
+{"issue_id":"005-002","type":"feature","title":"Task Acceptance Traceability via acceptance_criteria Links","status":"COMPLETED","source_file":"specs/005-acceptance-gates/issues/002-task-acceptance-traceability.md","blocked_by":["005-001"],"coordinates_with":["005-001"],"timestamp":"2026-08-19T06:29:00.116916Z","created_at":"2026-08-14T12:28:47.898898Z","flow_refs":[]}
+{"issue_id": "ISS-ADH-016", "type": "adhoc", "title": "Single-Source Prompt Templates \u2014 Auto Canonical, Manual Derived at Install", "status": "BACKLOG", "source_file": "specs/adhoc/issues/016-single-source-prompt-templates.md", "blocked_by": [], "coordinates_with": ["ISS-ADH-013"], "timestamp": "2026-08-20T06:56:22.594714+00:00", "created_at": "2026-08-20T06:56:22.594714+00:00", "flow_refs": []}