deviatdd 2.24.1__tar.gz → 2.24.2__tar.gz

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

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

{deviatdd-2.24.1 → deviatdd-2.24.2}/PKG-INFO

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

{deviatdd-2.24.1 → deviatdd-2.24.2}/pyproject.toml

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

{deviatdd-2.24.1 → deviatdd-2.24.2}/specs/005-acceptance-gates/prd.md

@@ -105,7 +105,7 @@ sequenceDiagram
      - **Boundary Category**: A `manual` or `deferred` mode validates but requires no `test_ref` in the contract body.
   2. `AC-005-01-02` / `AO-001`: Validation keeps requiring Source Outline, Upstream Traceability, Current-Code Evidence, and Given/When/Then.
      - **Observable Result**: Removing any existing clause still fails validation.
-- **Downstream Shard Mapping**: Epic `005-acceptance-gates`, first issue.
+- **Downstream Shard Mapping**: FR traceability unit only; shard owns grouping.
 
 ### FR-005-02: Task Acceptance Traceability
 - **Description**: `TaskRecord` gains an optional `acceptance_criteria: list[CriterionLink] | None` field. `generate_jsonl_from_md` in `src/deviate/core/tasks_ledger.py` propagates task-to-criterion and criterion-to-test links into each generated task row. The field parses as absent for JSONL rows written by older CLI versions.
@@ -118,7 +118,7 @@ sequenceDiagram
      - **Happy Path**: `deviate meso tasks pre` emits rows with valid links.
      - **Error Category**: Malformed criterion id or missing `test_ref` on an automated link fails generation.
      - **Boundary Category**: Legacy JSONL rows without the field still parse under `extra="forbid"`.
-- **Downstream Shard Mapping**: Epic `005-acceptance-gates`, second issue.
+- **Downstream Shard Mapping**: FR traceability unit only; shard owns grouping.
 
 ### FR-005-03: Non-Blocking RED Checkpoint
 - **Description**: `_run_red_phase` in `src/deviate/cli/micro.py` stops raising `PhaseFailedError` on test returncode 0. It builds a `RedHandoffAdvisory` (`passes`, `severity`) and passes it in-memory to the GREEN runner. The RED phase always completes and appends its `RED` transition row. No persistent record is written.
@@ -133,7 +133,7 @@ sequenceDiagram
      - **Boundary Category**: No test file detected — the checkpoint is skipped.
   2. `AC-005-03-02` / `AO-003`: A RED run whose test suite fails completes with an `ok` advisory.
      - **Observable Result**: RED transition row appended; GREEN starts.
-- **Downstream Shard Mapping**: Epic `005-acceptance-gates`, third issue.
+- **Downstream Shard Mapping**: FR traceability unit only; shard owns grouping.
 
 ### FR-005-04: Blocking GREEN Gate with JUDGE Routing
 - **Description**: `_run_green_phase` requires `_run_test_cmd` returncode 0. On failure it sets `train_feedback` and routes to JUDGE, which decides retry GREEN or revert to RED, bounded by `_MAX_JUDGE_FEEDBACK = 3`. Verification mode never exempts the automated suite.
@@ -146,7 +146,7 @@ sequenceDiagram
      - **Happy Path**: Format cmd runs; GREEN result commits.
      - **Error Category**: Non-zero returncode routes to JUDGE via `train_feedback`.
      - **Boundary Category**: A `warning` RED advisory does not block GREEN start.
-- **Downstream Shard Mapping**: Epic `005-acceptance-gates`, fourth issue (may merge with FR-005-03).
+- **Downstream Shard Mapping**: FR traceability unit only; shard owns grouping.
 
 ### FR-005-05: Blocking REFACTOR Regression Gate
 - **Description**: `_run_refactor_phase` inspects the `_run_test_cmd` returncode. Non-zero raises `PhaseFailedError` and the task fails. Zero proceeds to format cmd, appends the `COMPLETED` transition, commits, and transitions the session to `IDLE`.
@@ -159,7 +159,7 @@ sequenceDiagram
      - **Happy Path**: All tests pass after polish; `COMPLETED` row appended.
      - **Error Category**: Non-zero returncode raises and records failure.
      - **Boundary Category**: Tests unchanged and passing — gate passes without side effects.
-- **Downstream Shard Mapping**: Epic `005-acceptance-gates`, fifth issue.
+- **Downstream Shard Mapping**: FR traceability unit only; shard owns grouping.
 
 ### FR-005-06: Prompt Template and Specification Alignment
 - **Description**: Update `src/deviate/prompts/commands/deviate-red.md`, `src/deviate/prompts/auto/red.md`, `green.md`, and `refactor.md` to describe the checkpoint and gates. Update `specs/DeviaTDD-api.md` and `specs/DeviaTDD-architecture.md` gate semantics in the same commit. Append a `CHANGELOG.md` entry under `[Unreleased]`.
@@ -172,7 +172,7 @@ sequenceDiagram
      - **Happy Path**: Templates and specs match runner behavior.
      - **Error Category**: A stale rejection statement in any template fails review.
      - **Boundary Category**: CHANGELOG entry present under `[Unreleased]`.
-- **Downstream Shard Mapping**: Epic `005-acceptance-gates`, final issue.
+- **Downstream Shard Mapping**: FR traceability unit only; shard owns grouping.
 
 ## Acceptance Outline
 - `AO-001` / `AC-005-01-*`: Verification-mode metadata on `AC-PLAN-NNN` scenarios validates in `validate_acceptance_contract`.
@@ -188,7 +188,7 @@ sequenceDiagram
 - **Type Safety & Modularity**: Pydantic models enforce the schemas above. `ruff check` and `ruff format --check` pass. Coverage stays at or above 80%. Tests mock `deviate.cli.micro._run_pytest` where CLI commands reach it.
 
 ## Issue Sharding Strategy
-Shard the epic into 5-6 issues, one per FR: contract metadata (`FR-005-01`), task traceability (`FR-005-02`), RED checkpoint (`FR-005-03`), GREEN gate (`FR-005-04`), REFACTOR gate (`FR-005-05`), and template/spec alignment (`FR-005-06`). `FR-005-04` may merge with `FR-005-03` into one slice. Each issue keeps its own `plan.md` `AC-PLAN-NNN` acceptance contract with verification-mode metadata.
+This PRD lists FRs as traceability units only. It does not prescribe issue count, issue IDs, or shard topology. Related FRs may share one independently testable vertical (for example FR-005-03 and FR-005-04 as one RED/GREEN gate behavior), and a single FR may split across issues when each issue owns a distinct observable behavior. Shard owns grouping, boundaries, and the dependency DAG.
 
 ## Ambiguity Resolution and Stakeholder Decisions
 - `RESOLVED-Q-001` (HITL-001): RED checkpoint storage ➔ **Resolution Requirement Invariant**: The checkpoint is an in-memory phase-handoff advisory; the system writes no persistent record, no ledger field, and no `.deviate/` store.

{deviatdd-2.24.1 → deviatdd-2.24.2}/specs/DeviaTDD-api.md

@@ -1579,9 +1579,9 @@ and are installed to `.{agent}/commands/<name>.md` per workspace (or `.pi/prompt
 
 | Client Command Trigger | Responsible Persona Role | Targets Created / Mutated | Internal CLI Endpoints | Action Logic Steps |
 | --- | --- | --- | --- | --- |
-| `/deviate-explore` | Context Scanner (Cheap) | `specs/{FEATURE_SLUG}/explore.md` | `deviate feature create`, `deviate explore pre/post` | 6 steps: feature create, constitution validate, bucket allocate, codebase scan, write explore.md, commit |
-| `/deviate-research` | Architect (Expensive) | `specs/{FEATURE_SLUG}/design.md`, `data-model.md` | `deviate research pre/post` | 5 steps: read explore.md, analyze options, produce design.md, produce data-model.md, commit |
-| `/deviate-prd` | Product Owner Proxy | `specs/{FEATURE_SLUG}/prd.md` | `deviate prd pre/post` | 4 steps: read design.md, synthesize requirements, write prd.md, commit |
+| `/deviate-explore` | Context Scanner (Cheap) | `specs/{FEATURE_SLUG}/explore.md` | `deviate feature create`, `deviate explore pre/post` | 6 steps: feature create, constitution validate, bucket allocate, codebase scan (plus sibling-flow inventory when a nearest user flow exists), write explore.md, commit |
+| `/deviate-research` | Architect (Expensive) | `specs/{FEATURE_SLUG}/design.md`, `data-model.md` | `deviate research pre/post` | 5 steps: read explore.md, write the floor then attack it in one agent / two ordered jobs (no sequential sub-agent spawn), produce design.md + data-model.md (schema = floor only), commit. Existing constitutions stay read-only except greenfield bootstrap. |
+| `/deviate-prd` | Product Owner Proxy | `specs/{FEATURE_SLUG}/prd.md` | `deviate prd pre/post` | 4 steps: read design.md + data-model.md, halt on `UPSTREAM_INCONSISTENT` / `SCOPE_DRIFT`, synthesize floor + promoted extras (unused Recommended/Deferred stay out of scope), write prd.md, commit |
 | `/deviate-shard` | Decomposition Engine | `specs/{FEATURE_SLUG}/issues/{ORDINAL}-{slug}.md` (filenames use the per-epic ordinal; the ledger id is `{epic-prefix}-{ORDINAL}`, e.g. `002-001`) | `deviate shard pre/post` | 5 steps: read prd.md, identify vertical slices, validate granularity, create issue stubs with `AO-NNN` acceptance outlines (no Gherkin), register in ledger. PRD/Shard/Adhoc halt with `GHERKIN_LEAK_DETECTED` on bold `**Given**`/`**When**`/`**Then**`; final Gherkin belongs to Plan. New issues emit `{epic-prefix}-{ordinal}` ids; legacy `ISS-NNN` ids still resolve. |
 | `/deviate-adhoc` | Condensed Scoper | `specs/adhoc/` | `deviate adhoc pre/post` | 8 steps: complexity gate, codebase scan, PRD append, issue generation with remote-aware `NNN` (`max(origin ledger, current ledger, remote feat/adhoc/<NNN>-*) + 1`; `ISS-ADH-NNN` and `ISS-NNN` are one series; local-only branches do not reserve), ledger registration, commit, Gherkin-leak guard |
 | **[REMOVED]** | --- | --- | --- | HITL Gate 2 (post-Tasks `deviate meso approve` approval) was removed. The system never blocks on human approval; `deviate run` chains meso into micro end-to-end. Plan and Tasks still commit authored artifacts to the worktree, but the human can review them on their own schedule without gating execution. |

{deviatdd-2.24.1 → deviatdd-2.24.2}/specs/DeviaTDD-architecture.md

@@ -87,9 +87,9 @@ To maintain strict operational focus and establish explicit boundaries of respon
 
 ### 2.1 The Macro Layer: Feature Scoping
 Breaks a business goal down into standard development project containers.
-* **Explore (Cheap Context Gathering):** Fast, inexpensive scan of codebase structure, dependencies, existing patterns, and tech stack. Runs on a cheap model (V4 Flash). Outputs raw factual context to `explore.md` — what exists, not what to do. Initial output lands in `specs/explore/<slug>.md`; `deviate research pre` **moves** that file into the numbered epic directory at `specs/{NNN}-<slug>/explore.md` so every artifact for one feature lives under a single directory. `allocate_feature_bucket()` numbers an unnumbered slug from `max(local numbered specs dirs ∪ remote feat/<NNN>-* prefixes) + 1`; a numbered slug stays idempotent. The move is recorded as a tracked rename (usually rendered as `R100` in `git show`) inside the same atomic commit that `deviate research post` produces for `design.md` + `data-model.md` — the source path `specs/explore/<slug>.md` is `git rm`-ed and the destination `specs/{NNN}-<slug>/explore.md` is `git add`-ed, so the working tree never carries a tracked-but-deleted or untracked residue from the move. The source path is persisted on `SessionState.research_explore_source` at pre time so the post-script can `git rm` the right path even when `allocate_feature_bucket` short-circuits on an already-numbered slug.
-* **Research (Architectural Design):** Consumes `explore.md` (at `specs/{NNN}-<slug>/explore.md` after the research pre move) and performs high-level architectural analysis: trade-offs, options matrix, design decisions, and data modeling. Runs on a reasoning model (Qwen thinking or V4 Pro). Outputs `design.md` (architecture and decisions) and `data-model.md` (entity relationships, schemas), both inside the same numbered epic directory.
-* **PRD:** Translates `design.md` into immutable FR/AC tokens plus implementation-independent `AO-NNN` acceptance outlines. Given/When/Then is forbidden here; Plan owns final Gherkin.
+* **Explore (Cheap Context Gathering):** Fast, inexpensive scan of codebase structure, dependencies, existing patterns, and tech stack. Runs on a cheap model (V4 Flash). Outputs raw factual context to `explore.md` — what exists, not what to do. When a nearest existing user flow exists, catalog a short sibling-flow inventory (amount vs fee, lock vs reserve, vendor call in HTTP vs job, idempotency, destination shape) with quoted paths and no recommendations. Ecosystem research stays catalog only. Initial output lands in `specs/explore/<slug>.md`; `deviate research pre` **moves** that file into the numbered epic directory at `specs/{NNN}-<slug>/explore.md` so every artifact for one feature lives under a single directory. `allocate_feature_bucket()` numbers an unnumbered slug from `max(local numbered specs dirs ∪ remote feat/<NNN>-* prefixes) + 1`; a numbered slug stays idempotent. The move is recorded as a tracked rename (usually rendered as `R100` in `git show`) inside the same atomic commit that `deviate research post` produces for `design.md` + `data-model.md` — the source path `specs/explore/<slug>.md` is `git rm`-ed and the destination `specs/{NNN}-<slug>/explore.md` is `git add`-ed, so the working tree never carries a tracked-but-deleted or untracked residue from the move. The source path is persisted on `SessionState.research_explore_source` at pre time so the post-script can `git rm` the right path even when `allocate_feature_bucket` short-circuits on an already-numbered slug.
+* **Research (Architectural Design):** Consumes `explore.md` (at `specs/{NNN}-<slug>/explore.md` after the research pre move) and performs high-level architectural analysis as a **range**, not a maxed design. One agent writes the floor (constitution + sibling parity + authorization/money safety/provider correctness/data integrity) then attacks it in the same prompt — no sequential AlphaBeta/Gamma sub-agent spawns. Schema tables are floor only; named extras live in a Deferred / maximal bracket list. Existing constitutions stay read-only except greenfield bootstrap or an explicit HITL amendment. Runs on a reasoning model (Qwen thinking or V4 Pro). Outputs `design.md` (architecture and decisions) and `data-model.md` (entity relationships, schemas), both inside the same numbered epic directory.
+* **PRD:** Translates the human-selected point on the research bracket into immutable FR/AC tokens plus implementation-independent `AO-NNN` acceptance outlines. In-scope is the floor plus promoted extras; unused Recommended/Deferred extras stay in Out-of-Scope Boundaries. Halt with `UPSTREAM_INCONSISTENT` when `design.md` and `data-model.md` disagree on a field, state, or storage type, and `SCOPE_DRIFT` when a required item has no approved upstream Required source. Given/When/Then is forbidden here; Plan owns final Gherkin.
 * **Shard:** Breaks down the PRD into standalone technical issue files (GitHub Issues). Each issue must be a **vertical slice** — a complete, testable behavior end-to-end (not a horizontal layer like "add database"). Emit as few independently shippable user-visible verticals as the PRD needs. Enforce bounds: minimum 1 issue, maximum 10 issues. A single-issue shard is valid (the option to have used `/deviate-adhoc` has passed by the time shard runs). Each issue must be independently implementable and testable, with clear acceptance criteria. **Slicing rules live entirely in the `deviate-shard` prompt** (Pass 1 flow-anchored clustering, Pass 1.5 hard cap with `SLICE_CAP_EXCEEDED`, Pass 3.5 horizontal-slice merging); the PRD prompt only shapes FRs via flow-segment authoring guidance, never pre-decides groupings.
 * **Adhoc (Fast-Path):** A condensed single-command shortcut (`/deviate-adhoc`) that compresses Explore + Research + PRD + Shard into one operation for low-to-medium complexity tasks. Performs proportional exploration (lightweight file scanning, dependency mapping), synthesizes a condensed PRD entry, and emits a single vertical-slice issue directly into `specs/adhoc/`. Appends to the aggregated `specs/adhoc/prd.md` and registers the issue in the global `specs/issues.jsonl` append-only ledger with an `ISS-NNN` / `ISS-ADH-NNN` identifier (one adhoc series). The compiler allocates `NNN` as `max(origin ledger, current ledger, remote feat/adhoc/<NNN>-*) + 1`. Local-only unpushed feat branches do not reserve. A **Complexity Gate** evaluates the task description before proceeding: high-complexity tasks (multi-module coordination, state management, new architecture) are rejected with a directive to run `/deviate-explore` to initiate a full epic workflow instead. This gate prevents scope-creep and ensures adhoc remains a true fast-path, not a bypass for complex engineering.
 * **Greenfield bootstrap:** `deviate explore pre` and `deviate research pre` are the two

{deviatdd-2.24.1 → deviatdd-2.24.2}/src/deviate/prompts/auto/explore.md

@@ -13,6 +13,8 @@ Your job is to ingest a JSON contract emitted by `deviate explore pre`, perform
 ### Phase-Specific Invariants
 
 1. **Factual-Only Discipline**: Emit only what EXISTS. Trade-off analysis, recommendations, design decisions, and risk evaluations are explicitly deferred to `/research`. Prefer observational language ("the project contains", "the manifest declares") over prescriptive language ("we should", "we recommend").
+2. **Sibling-Flow Inventory**: When a nearest existing user flow exists, catalog it as fact before `explore.md` is complete. Cover amount vs fee, lock vs reserve, vendor call in HTTP vs job, idempotency, and destination shape. Quote paths. Do not recommend.
+3. **Ecosystem Catalog Only**: `## Ecosystem Research` is a catalog. Later phases must not treat those rows as Required unless a local flow, constitution clause, or money/auth/provider integrity test applies.
 
 </system_instructions>
 
@@ -23,7 +25,7 @@ Persona: Senior Codebase Forensics Engineer & Structural Discovery Subagent.
 ABSOLUTE RULE: This agent is DISCOVERY ONLY. It reads files and catalogs what exists. It does NOT write, edit, create, or modify ANY file. It does NOT generate code, tests, configs, or scripts. It returns ONLY text fragments to the orchestrator.
 
 Objective: Walk the local file tree under `repo_root` and produce a factual inventory of observed artifacts. NO analysis, NO recommendations, NO trade-off evaluation, NO failure-mode speculation, NO code generation.
-Output Scope: Populate fragments for `## Discovery Audit Results`, `## File Registry`, and `## Constitution Quotes`. Return these as text fragments only — do NOT write any files.
+Output Scope: Populate fragments for `## Discovery Audit Results`, `## File Registry`, `## Constitution Quotes`, and `## Sibling Flow Inventory`. Return these as text fragments only — do NOT write any files.
 Instructions:
 - Run only read-only structural searches and file listings. Use the codebase-index tools as the primary discovery path: verify the index is current via `index_status`; use `codebase_peek` for symbol and file existence lookups, `codebase_search` for semantic discovery, `implementation_lookup` for symbol definitions, and `call_graph` for call relationships. Supplement with `find`, `tree -L 3`, glob expansions, and `cat`/`head` for last-mile regex patterns, raw text reads, and dotfiles gitignored from the index.
 - Never use tools that modify files (Create, Edit, Write, ApplyPatch, etc.). If only such tools are available, terminate and report the limitation.
@@ -34,6 +36,7 @@ Instructions:
 - For every entry captured for the FILE_REGISTRY, capture a verbatim snippet (≤ 10 lines) at the moment of tool extraction.
 - NEVER run test, lint, type-check, build, or formatting commands. These are implementation-phase operations.
 - NEVER create, write, modify, or patch any source file, test file, configuration, or script.
+- When a nearest existing user flow exists (a parallel path the new feature would sit beside), catalog it under `## Sibling Flow Inventory`: amount vs fee, lock vs reserve, vendor call in HTTP vs job, idempotency, destination shape. Quote paths. Do not recommend. If none exists, return `None observed`.
 
 **Targeted Architectural Baselines (Hunt for these 5 categories):**
 1. **Existing Architectural Patterns**: Routing/entry points, domain models, error handling patterns (e.g., Railway pattern, global handlers).
@@ -60,7 +63,8 @@ Instructions:
 - Use `libref list` to check what documentation sources are already available. Use `libref query <lib> "<topic>"` for offline, version-pinned documentation. If the library is not in libref, use web search or web fetch tools directly to query documentation, authoritative blogs, and standard library references.
 - Focus on: (1) Best practices for the specific problem domain, (2) Common use cases and pitfalls, (3) Standard tools/libraries that solve this problem in the language/framework identified in the constitution.
 - For every finding, capture the source URL and a brief verbatim snippet (≤ 10 lines) or a precise summary of the finding.
-- Do NOT make architectural recommendations or trade-off evaluations. Simply catalog what the ecosystem says.
+- Do NOT make architectural recommendations or trade-off evaluations. Simply catalog what the ecosystem says. This section is catalog only.
+- Later phases must not treat these rows as Required unless a local flow, constitution clause, or money/auth/provider integrity test applies.
 - If web search tools are unavailable, report `WEB_SEARCH_UNAVAILABLE` and skip this subagent; the orchestrator will proceed with local findings only.
 </subagent_ecosystem_prompt>
 </subagent_blueprint_directory>
@@ -70,6 +74,7 @@ Instructions:
 2. **Structural Audit Mandate**: Catalog every manifest, dependency declaration, test entry point, and architectural baseline observed in the repo. No interpretation — only observation.
 3. **Grounding Rule**: Every row in the file registry MUST carry a verbatim snippet (≤ 10 lines). Rows without verbatim quotes are rejected by the post-script.
 4. **Constitutional Quoting**: Quote the constitution sections verbatim in `## Constitution Quotes`. Do not classify, score, or interpret.
+5. **Sibling-Flow Mandate**: When a nearest existing user flow exists, `## Sibling Flow Inventory` quotes paths for amount vs fee, lock vs reserve, vendor call location, idempotency, and destination shape. Do not recommend.
 </traceability_mandates>
 
 <execution_sequence>
@@ -84,7 +89,7 @@ If `is_greenfield` is false, capture `Tech Stack Standards`, `Testing Protocols`
 </step>
 <step id="exploratory_scan">
 For non-trivial repos, invoke the TWO structural subagents defined in `<subagent_blueprint_directory>` in parallel:
-- **Codebase Scanner**: Produces fragments for `## Discovery Audit Results`, `## File Registry`, `## Constitution Quotes`, and `## Architectural Baselines`.
+- **Codebase Scanner**: Produces fragments for `## Discovery Audit Results`, `## File Registry`, `## Constitution Quotes`, `## Architectural Baselines`, and `## Sibling Flow Inventory`.
 - **Ecosystem Researcher**: Produces fragments for `## Ecosystem Research`.
 
 For trivial repos (one-file, one-script, single-language micro-projects), collapse to a single linear pass: walk the tree yourself, read the manifest(s), and produce the same fragments inline.
@@ -92,8 +97,12 @@ For trivial repos (one-file, one-script, single-language micro-projects), collap
 Both subagents are read-only. They do NOT write files, generate code, run tests, or make any modifications.
 </step>
 
+<step id="sibling_flow_inventory">
+Before `explore.md` is complete, catalog the nearest sibling user flow when one exists. Quote paths. Do not recommend. Cover: amount vs fee, lock vs reserve, vendor call in HTTP vs job, idempotency, destination shape. If none exists, write `None observed`.
+</step>
+
 <step id="evidence_compilation">
-Merge fragments into the final output. Enforce relative paths and verbatim evidence. If manifest-declared dependencies conflict with constitution quotes, surface both verbatim — do not adjudicate.
+Merge fragments into the final output. Enforce relative paths and verbatim evidence. If manifest-declared dependencies conflict with constitution quotes, surface both verbatim — do not adjudicate. Ecosystem rows stay catalog only.
 </step>
 
 <step id="single_explore_md_output">
@@ -141,7 +150,21 @@ Read the `## Scope Sizing` section you compiled. Use `Estimated Complexity` to r
 - **Quality, Safety & Observability**
 - **External Integrations**
 
+## Sibling Flow Inventory
+When a nearest existing user flow exists, catalog it as fact. Quote paths. Do not recommend.
+
+| Dimension | Observed fact | Path |
+| :--- | :--- | :--- |
+| Amount vs fee | [separate amount + fee / single amount / none observed] | [relative/path] |
+| Lock vs reserve | [lock / reserve-consume-release / none observed] | [relative/path] |
+| Vendor call | [HTTP request path / job / none observed] | [relative/path] |
+| Idempotency | [one vendor create / retry / none observed] | [relative/path] |
+| Destination shape | [typed snapshot / generic payload / none observed] | [relative/path] |
+
+If no nearest sibling exists, write `None observed` under this heading.
+
 ## Ecosystem Research
+Catalog only. Later phases must not treat these rows as Required unless a local flow, constitution clause, or money/auth/provider integrity test applies.
 - **Best Practices**
 - **Common Use Cases & Pitfalls**
 - **Standard Tooling**
@@ -190,10 +213,4 @@ EVERY row MUST carry its verbatim quote excerpt. Rows without a verbatim quote a
 | Manifest-constitution divergence observed | Quote BOTH verbatim; flag in Discovery Audit Results — do not adjudicate. |
 | Agent attempts to write/modify implementation code, tests, configs, or scripts | Halt with IMPLEMENTATION_DRIFT_DETECTED. |
 | Agent attempts to run test/lint/type-check/build commands | Halt with FORBIDDEN_COMMAND_ATTEMPTED. |
-
-
-<context>
-<user_input>
-$ARGUMENTS
-</user_input>
-</context>
+| No nearest sibling user flow | Write `None observed` under `## Sibling Flow Inventory`. |

{deviatdd-2.24.1 → deviatdd-2.24.2}/src/deviate/prompts/auto/plan.md

@@ -161,9 +161,3 @@ next_phase: "TASKS"
 | `specs/_product/` directory absent | Emit `- **Flow References**: []` under `## Product Layer Anchors` and plan only the application behavior. Do not add Product-layer or DeviaTDD setup work. |
 
 </edge_case_handling>
-
-<context>
-<user_input>
-$ARGUMENTS
-</user_input>
-</context>

{deviatdd-2.24.1 → deviatdd-2.24.2}/src/deviate/prompts/auto/prd.md

@@ -4,22 +4,29 @@
 
 You are a **PRODUCT_REQUIREMENTS_COMPILER** operating inside the **MACRO LAYER / PHASE_PRD**. Your objective is to ingest the architectural design (`design.md`) and data model (`data-model.md`) and compile them into an integrated, production-grade Product Requirements Document (`prd.md`). This document serves as the singular, deeply coherent source of truth for downstream automated sharding into local issues.
 
+The human selects the point on the research bracket. In-scope = floor + promoted extras. Promoting a sketched extra is PRD-only (no research rerun). No sketch → halt; do not invent a third money definition.
+
 Your job is to ingest a JSON contract emitted by `deviate prd pre`, compile the PRD content from upstream artifacts, write `<prd_path>`, then invoke the post-script.
 
 ### Phase-Specific Invariants
 
-1. **Cohesive Scope Invariant**: Evaluate the specified architecture as an un-fragmented whole. Every functional mechanism, guardrail, or operational exception must have an explicit tracking match in the structural entities.
+1. **Selected-Scope Invariant**: Every mechanism selected for the approved architecture must have a tracking match. Unselected mitigations remain out of scope.
+
+2. **Downstream Sharding Readiness**: Every FR has stable AC tokens and AO-NNN behavioral outlines. PRD MUST NOT emit Given/When/Then; final Gherkin belongs to Plan. FRs are traceability units only.
+
+3. **PRD Ownership (No Shard Topology)**: PRD owns behavior, constraints, acceptance criteria, and FR traceability. PRD MUST NOT prescribe issue count, issue IDs, or shard topology. Shard owns issue count, grouping, boundaries, and the dependency DAG.
 
-2. **Downstream Sharding Readiness**: Every FR has stable AC tokens and AO-NNN behavioral outlines. PRD MUST NOT emit Given/When/Then; final Gherkin belongs to Plan.
+4. **Ambiguity Interrogation**: If critical architectural parameters are unresolved, trigger AMBIGUITY_INTERROGATION — suppress PRD generation and emit only DECISION_READINESS and CLARIFICATION_LOG blocks.
 
-3. **Ambiguity Interrogation**: If critical architectural parameters are unresolved, trigger AMBIGUITY_INTERROGATION — suppress PRD generation and emit only DECISION_READINESS and CLARIFICATION_LOG blocks.
+5. **No Scope Promotion**: Do not promote `Recommended` or `Deferred` mitigations into FRs, NFRs, or acceptance criteria. Unused Recommended/Deferred extras belong under `## Out-of-Scope Boundaries` so the reviewer can pull one back in.
 
 </system_instructions>
 
 <traceability_mandates>
-1. **Verbatim Objective Verification**: Extract `{EPIC_SLUG}` from the contract. Trace every `FR-[ID]` token back to upstream design decisions in `design.md`.
+1. **Verbatim Objective Verification**: Extract `{EPIC_SLUG}` from the contract. Trace every `FR-[ID]` token back to an approved upstream Required source in `design.md` (floor or a human-promoted extra). `## Deferred` in `design.md` is **not** a PRD input for FRs.
 2. **Acceptance Outline Expansion**: Translate architectural criteria into observable `AO-NNN` outcomes traced to AC tokens, without implementation-specific Given/When/Then clauses. Halt with `GHERKIN_LEAK_DETECTED` on leakage.
 3. **Constitutional Compliance**: Every FR and AC must comply with the constitution's architectural principles and testing protocols.
+4. **Cross-Artifact Consistency**: Reproduce the approved `data-model.md` schema and state model exactly. Preserve approved `design.md` decisions. Do not silently choose one conflicting definition.
 </traceability_mandates>
 
 <execution_sequence>
@@ -36,12 +43,29 @@ Read constitution from `constitution_path`. Extract tech stack standards, testin
 Read `design_md_path` and `data_model_md_path` (if they exist), plus `explore_md_path`. If `explore_md_path` is missing or empty, halt with EXPLORE_MISSING.
 </step>
 
+<step id="upstream_consistency_gate">
+Before writing `prd.md`, compare every proposed field, state, transaction, job, metric, and policy with both approved research artifacts.
+
+- If `design.md` and `data-model.md` disagree on a field, state, or storage type: halt with `UPSTREAM_INCONSISTENT`. Do not invent a third money definition.
+- If a required item has no approved upstream Required source: halt with `SCOPE_DRIFT`.
+- Do not promote `Recommended` or `Deferred` into FRs, NFRs, or ACs.
+- In-scope = floor + extras the human promoted. Out-of-Scope Boundaries = unused Recommended/Deferred extras.
+- Promoting a sketched extra is PRD-only (no research rerun). No sketch → halt; do not invent a third money definition.
+- Keep code-level details only when the constitution or correctness requires that exact mechanism. Otherwise leave them for `plan.md`.
+- Keep as Required (do not weaken): authorization/ownership, money amount + fee, reserve/consume/release atomicity, skip_locked claim, one vendor create / no auto-resubmit, UNKNOWN vs fail-open, typed destination snapshot, constitution mandates.
+
+A blocking ambiguity is one that changes: authorization or ownership; money amount, fee, reserve, consume, or release behavior; persistence schema or state transitions; provider safety or idempotency; externally observable behavior; a constitutional requirement.
+
+Metrics, file paths, scheduler tuning, and future adapters are non-blocking unless an approved artifact or constitution makes them required.
+</step>
+
 <step id="prd_generation">
 Generate the PRD content following the output format schema. Write to `prd_path`.
 - All `FR-[ID]`, `AC-[ID]`, and `AO-[ID]` tokens must be unique and sequential.
 - Acceptance outlines MUST NOT contain bold Given/When/Then clauses.
 - Every path must be relative to `repo_root`.
 - Constitutional constraints must be respected.
+- Do not add new mandatory PRD sections, a recommendations.md artifact, or a full ops-hardening FR set.
 </step>
 
 <step id="manifest_writing">
@@ -70,12 +94,16 @@ The CLI orchestrator runs `deviate prd post` after your response to validate `pr
 # System Objectives and Scope Boundary
 ## Core Value Proposition
 ## In-Scope Boundaries (Hard Directives)
+Floor plus extras the human promoted.
 ## Out-of-Scope Boundaries (Defensive Exclusions)
+Unused Recommended/Deferred extras from research, so the reviewer can pull one back in. Unselected mitigations remain out of scope.
 
 # Architectural Constraints and Prerequisites
 ## Data Models & Invariants
+Reproduce the approved `data-model.md` schema and state model exactly.
 ## Performance / Scalability Thresholds
 ## Security & Compliance Invariants
+authorization/ownership; amount + fee; reserve/consume/release; skip_locked; one vendor create; UNKNOWN vs fail-open; typed destination snapshot.
 
 # Functional Flow and Sequence Architecture
 ## System Orchestration Mapping
@@ -93,6 +121,7 @@ The CLI orchestrator runs `deviate prd post` after your response to validate `pr
 
 # Non-Functional Engineering Requirements
 # Issue Sharding Strategy
+FRs are traceability units only. Do not prescribe issue count, issue IDs, or shard topology. Leave grouping, boundaries, and the dependency DAG to shard.
 # Ambiguity Resolution and Stakeholder Decisions
 # Session State
 </output_format_schemas>
@@ -103,12 +132,7 @@ The CLI orchestrator runs `deviate prd post` after your response to validate `pr
 | Pre-script returns NO_EPIC | Surface error; no feature workspace found. |
 | PRD has missing FR or AC tokens | Halt with MALFORMED_PRD_CONTRACT. |
 | explore_md_path missing or empty | Halt with EXPLORE_MISSING. |
+| design.md and data-model.md disagree on a field, state, or storage type | Halt with `UPSTREAM_INCONSISTENT`. Do not invent a third money definition. |
+| Required item with no approved upstream Required source | Halt with `SCOPE_DRIFT`. |
 | Ambiguity found in upstream data | Trigger AMBIGUITY_INTERROGATION state, suppress PRD generation, emit only DECISION_READINESS + CLARIFICATION_LOG. |
 </edge_case_handling>
-
-
-<context>
-<user_input>
-$ARGUMENTS
-</user_input>
-</context>