deviatdd 2.5.3__tar.gz → 2.5.5__tar.gz

{deviatdd-2.5.3 → deviatdd-2.5.5}/CHANGELOG.md

@@ -113,6 +113,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Previously it only updated the ledger after an external merge. The `deviate
   merge` CLI command is unchanged — the prompt now drives it as a final step
   rather than relying on an external squash-merge tool.
+- Active domain discipline applied to `/deviate-research`, `/deviate-prd`, `/deviate-flows`, and `/deviate-architecture`. Each phase now actively term-challenges against the relevant glossary (`data-model.md`, `domain-model.md`, `flows-product.md`), sharpens fuzzy language, stress-tests with concrete scenarios, and updates the artifact inline as terms resolve. The macro-layer `interactive_hitl_gate_1` and the PRD `AMBIGUITY_INTERROGATION` gate now require a discipline pass before presenting HITL questions; the Product-layer discovery steps are upgraded from passive 3–4 bullet blocks to structured 7–8 bullet active disciplines. Spec alignment: `specs/DeviaTDD-architecture.md` §2.1 and §5.0, `specs/DeviaTDD-api.md` §1.5 and §2.
 
 ### Fixed
 - `resolve_issue_record` and `_deduplicate_issues` now treat `COMPLETED`

{deviatdd-2.5.3 → deviatdd-2.5.5}/PKG-INFO

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

{deviatdd-2.5.3 → deviatdd-2.5.5}/pyproject.toml

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

{deviatdd-2.5.3 → deviatdd-2.5.5}/specs/DeviaTDD-api.md

@@ -151,6 +151,8 @@ The Product layer ships as **agent skills** (no dedicated CLI subcommands) — t
 
 **Downstream consumption:** `deviate-shard` and `deviate-adhoc` SKILL.md bodies read `specs/_product/flows/`, `specs/_product/release-next.md`, `specs/_product/architecture.md`, and `specs/_product/domain-model.md` as authoritative context. Each sharded or adhoc issue emits a `flow_refs: [FLOW-XX, ...]` field in its YAML frontmatter and in the `IssueRecord.flow_refs` ledger entry (validated against `^FLOW-\d{2,}$`), so vertical slices stay traceable back to the flow that motivated them. `deviate adhoc pre` accepts a `--flow-ref FLOW-01,FLOW-02` CLI override to set the flow refs explicitly when the agent's natural-language inference is ambiguous.
 
+**Active Domain Discipline** is enforced at HITL gates: the Product-layer discovery steps (`/deviate-flows`, `/deviate-architecture`) follow a structured 7–8 bullet active discipline — one question at a time with a recommended answer, dependency-ordered, read-first, term-challenge against the glossary, sharpen fuzzy language, stress-test with scenarios, and update the artifact (`flows-<domain>.md` or `domain-model.md`) inline as terms resolve.
+
 #### `/deviate-shard` (Macro Layer)
 
 * **Objective:** Decomposes the PRD into standalone, testable issue files.
@@ -170,6 +172,8 @@ All macro-layer commands follow the `pre`/`post` subcommand pattern (except `ini
 Every `pre` subcommand accepts `--json` (emit JSON contract to stdout) and `--quiet`
 (suppress diagnostic output).
 
+**Active Domain Discipline** is enforced at HITL gates: the macro phases that interact with the human (`/deviate-research` Gate 1, `/deviate-prd` Ambiguity Interrogation, `/deviate-shard` Gate 2) actively term-challenge against the upstream glossary, sharpen fuzzy language, stress-test with concrete edge-case scenarios, and update the relevant artifact (`design.md`, `data-model.md`, `prd.md`) inline as terms resolve — not as a passive sign-off step.
+
 #### `deviate explore pre <problem> [--slug]`
 
 * **Source:** `src/deviate/cli/macro.py`

{deviatdd-2.5.3 → deviatdd-2.5.5}/specs/DeviaTDD-architecture.md

@@ -73,6 +73,8 @@ Breaks a business goal down into standard development project containers.
 * **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"). Target 4-8 issues per feature shard. 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 `ADH-{NNN}` identifier. 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.
 
+* **Active Domain Discipline (HITL gates):** The macro phases that interact with the human (`/deviate-research` Gate 1, `/deviate-prd` Ambiguity Interrogation, `/deviate-shard` Gate 2) actively term-challenge against the upstream glossary, sharpen fuzzy language, stress-test with concrete edge-case scenarios, and update the relevant artifact (`design.md`, `data-model.md`, `prd.md`) inline as terms resolve — not as a passive sign-off step.
+
 ### 2.2 The Meso Layer: Issue Engineering
 Creates formal contracts for an issue via CLI slash commands. The workflow was restructured
 (ADHOC-003) to merge `/deviate-specify` into `/deviate-shard` and introduce a dedicated
@@ -348,6 +350,8 @@ The Product layer captures cross-product framing (FLOW-01..FLOW-03). It is optio
     * *System Directives:* Accept a release-goal description from the user; compile the next coherent product release from the existing flows and architecture; write or override `specs/_product/release-next.md` (Included Flows table, Included Work table, Acceptance Criteria). Downstream `/deviate-explore` and other prompts treat `specs/_product/release-next.md` as the guiding compass when deciding what the next epic should be.
 * **Downstream consumption:** `deviate-shard` and `deviate-adhoc` SKILL.md bodies read `specs/_product/flows/`, `specs/_product/release-next.md`, `specs/_product/architecture.md`, and `specs/_product/domain-model.md` as authoritative context. Each sharded issue emits a `flow_refs: [FLOW-XX, ...]` field in its YAML frontmatter (and in the `IssueRecord.flow_refs` ledger entry), so vertical slices stay traceable back to the flow that motivated them.
 
+* **Active Domain Discipline:** Both `/deviate-flows` and `/deviate-architecture` discovery steps use a structured 7–8 bullet active discipline — one question at a time with a recommended answer, dependency-ordered, read-first, term-challenge against the glossary, sharpen fuzzy language, stress-test with scenarios, and update the artifact (`flows-<domain>.md` or `domain-model.md`) inline as terms resolve. Enforced as a mandatory pass before writing the flow file or architecture entry.
+
 ### 5.1 Meso Layer Phase Prompts
 * **`/deviate-specify` (Deprecated):** Merged into `/deviate-shard`. Shard now produces spec-enriched issue files directly. The legacy skill remains for backward compatibility with a redirect notice.
 * **[HITL Gate 2]:** Human reviews all sharded issue files (with embedded spec content) for completeness, edge cases, scope correctness. Moved from after `/deviate-specify` to after `/deviate-shard`.

{deviatdd-2.5.3 → deviatdd-2.5.5}/src/deviate/prompts/commands/deviate-architecture.md

@@ -86,19 +86,15 @@ Ask the user to describe the new architectural surface or modification. For
 greenfield architectures, prompt for: components, integration contracts, data
 ownership, and the flow IDs each component serves.
 
-**Discovery discipline** (adapted from the "grill with docs" pattern):
-- Ask ONE question at a time. For each question, provide your recommended
-  answer. Wait for the human's response before asking the next.
-- Walk the decision tree dependency-first: resolve components before
-  integration contracts, contracts before data ownership.
-- If a question can be answered by reading the codebase, existing flows,
-  or `domain-model.md`, do that instead of asking.
-- **Term-challenging** (at most once per turn): if the user's term
-  conflicts with an existing definition in `domain-model.md` or
-  `architecture.md`, call it out immediately — "Your domain model
-  defines X as Y, but you seem to mean Z — which is it?" If the user
-  uses a vague term ("account", "thing", "service"), propose a canonical
-  name. Do not loop on challenges — surface once, then move on.
+**Discovery discipline** (adapted from the "grill with docs" pattern, made active):
+- **Ask ONE question at a time**, with your recommended answer, and wait for the human's response before asking the next. Do not advance to the next question until the human has answered.
+- **Walk the decision tree dependency-first**: resolve components before integration contracts, contracts before data ownership.
+- **Read first, ask second**: if a question can be answered by reading the codebase, existing flows, `domain-model.md`, or `architecture.md`, do that instead of asking.
+- **Term-challenge against the glossary** (at most once per turn): if the user's term conflicts with an existing definition in `domain-model.md` or `architecture.md`, call it out immediately — "Your domain model defines X as Y, but you seem to mean Z — which is it?" Propose a canonical name for vague terms ("account", "thing", "service"). Do not loop on challenges — surface once, then move on.
+- **Sharpen fuzzy language**: when the user names a component with a vague term, propose a precise canonical name and confirm before writing the architecture entry.
+- **Stress-test with scenarios**: for each new component or contract, invent one concrete failure scenario ("what happens when the message bus is down at handoff time?") and ask the human to confirm the degraded behavior.
+- **Update domain-model.md inline**: as entities and relationships resolve, mirror them in `specs/_product/domain-model.md` immediately. Do not batch up the corrections — capture them as they happen.
+- **Offer ADRs sparingly**: when a decision meets all three criteria (hard to reverse, surprising without context, real tradeoff), append a one-paragraph ADR per invariant 9. Do not propose ADRs for routine component selections.
 
 ## 4. Classify the Change
 Apply the Local / Context-Bridging / Context-Creating classification

{deviatdd-2.5.3 → deviatdd-2.5.5}/src/deviate/prompts/commands/deviate-flows.md

@@ -98,13 +98,14 @@ CRITICAL INVARIANTS:
 
 Read `<user_input>` first; if empty, parse conversational history.
 
-**Discovery discipline** (adapted from the "grill with docs" pattern):
-- Ask ONE question at a time. For each question, provide your recommended
-  answer. Wait for the human's response before asking the next.
-- Walk the dependency tree: resolve Actor before Domain, Domain before
-  Trigger, Trigger before Happy Path.
-- If a question can be answered by reading the codebase or existing flow
-  files, do that instead of asking.
+**Discovery discipline** (adapted from the "grill with docs" pattern, made active):
+- **Ask ONE question at a time**, with your recommended answer, and wait for the human's response before asking the next. Do not advance to the next question until the human has answered.
+- **Walk the dependency tree** dependency-first: resolve Actor before Domain, Domain before Trigger, Trigger before Happy Path.
+- **Read first, ask second**: if a question can be answered by reading the codebase, existing flow files, or `specs/_product/architecture.md`, do that instead of asking.
+- **Term-challenge against the glossary** (at most once per turn): if the user's term conflicts with `flows-product.md`, `specs/_product/domain-model.md`, or any existing `flows-<domain>.md`, call it out immediately — "The seed defines X as Y, but you seem to mean Z — which is it?" Propose a canonical name for vague terms ("account", "thing"). Do not loop on challenges — surface once, then move on.
+- **Sharpen fuzzy language**: when the user names the flow with a vague term, propose a precise canonical name and confirm before writing the `## FLOW-NN <Name>` header.
+- **Stress-test with scenarios**: for each happy-path step, invent one concrete edge case ("what if the user is offline when the trigger fires?") and ask the human to confirm the alternate-path behavior.
+- **Update flow file inline**: as terms and scenarios resolve, update the in-progress flow block immediately. Do not batch up the corrections — capture them as they happen.
 
 Ask targeted questions to clarify:
 - Actor (Developer / End-User / Operator / External System)

{deviatdd-2.5.3 → deviatdd-2.5.5}/src/deviate/prompts/commands/deviate-prd.md

@@ -17,6 +17,13 @@ This engine operates strictly as an isolated, production-grade Product Requireme
 
 CRITICAL INSTRUCTION INVARIANTS:
 1. **Ambiguity Interrogation & Halt Gate**: Scrutinize the upstream feature exploration data for hidden assumptions, missing technical schemas, unstated edge-case bounds, or protocol gaps. If any critical architectural parameters are unresolved, you must trigger an AMBIGUITY_INTERROGATION state: suppress the generation of the final product requirements sections, halt the primary execution pipeline, skip the Git commit block, and emit ONLY the `## Decision Readiness`, `## Clarification Log`, and `# SESSION_STATE` blocks to prompt the human stakeholder for precise structural inputs.
+
+   **Active domain discipline (during AMBIGUITY_INTERROGATION, before the human can resolve Q-{ID} items):**
+   - **Term-challenge**: when the user or any upstream artifact uses a term that conflicts with `design.md`, `data-model.md`, or constitution definitions, surface the conflict with both definitions and the user's apparent meaning.
+   - **Sharpen fuzzy language**: when FRs or ACs use vague terms ("account", "user", "session"), propose a canonical term and ask the human to confirm before proceeding.
+   - **Stress-test with scenarios**: for each FR or AC, invent one concrete edge-case scenario ("what happens when…") and ask the human to confirm the expected behavior before locking the AC.
+   - **Cross-reference with code**: when the user describes how something should work, check the codebase via `codebase_search` / `codebase_peek`. If the code disagrees, surface the contradiction.
+   - **Inline capture**: terms resolved during interrogation land directly in the `## Clarification Log` with the chosen definition and the rejected alternatives — do not batch these up.
 2. **Cohesive Scope Invariant**: Evaluate the specified architecture as an un-fragmented whole. Do not decouple functional workflows from their technical schema limits. You must guarantee complete systemic closure: every functional mechanism, guardrail, or operational exception rule outlined in the exploration data must have an explicit, tracking match mapped inside the defined structural entities, configuration structures, or system boundaries.
 3. **Execution Lifecycle Protocols (Internal ICoT)**: Before producing output parameters, execute three sequential mental passes inside an internal engineering ledger block:
     - Pass 1 (Topological Layout): Map out the relationship matrices between the incoming data inputs and systemic entities.

{deviatdd-2.5.3 → deviatdd-2.5.5}/src/deviate/prompts/commands/deviate-research.md

@@ -177,18 +177,19 @@ Write the entities, relationships, schemas, state transitions, and data flow int
 </step>
 
 <step id="interactive_hitl_gate_1">
-**HITL Gate 1 — Interactive Review.** After writing `<design_target>` and `<data_model_target>`, pause to get human feedback before finalizing:
-
-1. Use the `question` tool to present the key architectural decisions to the human operator. Ask specific questions about any items in `## Pending HITL Decisions` that need human judgment. For example:
-   - "The recommended architecture uses [Option A]. Do you approve, or would you prefer [Option B]?"
-   - "The data model defines [Entity] with [attribute]. Does this match your domain model?"
-   - "The design reverses the explore brief on [decision]. Do you accept this deviation?"
-
-2. Wait for the human's answers. If they request changes:
-   - Update `<design_target>` and/or `<data_model_target>` accordingly
-   - Update the `## Pending HITL Decisions` table: set resolved items to `RESOLVED`
-   - Return to the question step if further clarification is needed
-
+**HITL Gate 1 — Interactive Review.** After writing `<design_target>` and `<data_model_target>`, pause to get human feedback before finalizing. The interaction is **active**, not a sign-off: complete a full domain-discipline pass below before presenting the `## Pending HITL Decisions` questions.
+
+**Domain discipline (mandatory before requesting sign-off):**
+- **Term-challenge against glossary**: when the user or any subagent uses a term that conflicts with `<data_model_target>`, `specs/_product/domain-model.md`, or constitution definitions, call it out immediately with the conflicting definitions and the user's apparent meaning.
+- **Sharpen fuzzy language**: when terms like "service", "thing", or "account" appear without a precise definition, propose a canonical term and ask the human to confirm before continuing.
+- **Stress-test with scenarios**: for each major architectural decision and each new entity boundary, invent one concrete edge-case scenario ("what happens when…") and ask the human to confirm the expected behavior.
+- **Update glossary inline**: as terms resolve, update `<data_model_target>` immediately — do not batch these up. Capture the term, the chosen definition, and the rejected alternatives.
+- **Cross-reference with code**: when the user states how something works, check the codebase via `codebase_search` / `codebase_peek`. If the code disagrees, surface the contradiction.
+- **Suggest ADRs sparingly**: when a decision meets all three criteria (hard to reverse, surprising without context, real tradeoff), offer to record it as an ADR — `/deviate-architecture` owns the format and storage.
+
+**Question protocol** (after the discipline pass):
+1. Use the `question` tool to present the remaining `## Pending HITL Decisions` and any unresolved discipline-pass questions. Ask ONE question at a time, with your recommended answer, and wait for the human's response before asking the next.
+2. If the human requests changes: update `<design_target>` and/or `<data_model_target>`, update the `## Pending HITL Decisions` table (set resolved items to `RESOLVED`), and return to the question step if further clarification is needed.
 3. Once the human is satisfied, proceed to the post-script.
 
 Do NOT proceed to `prd` — that is the human's decision after this phase completes.

{deviatdd-2.5.3 → deviatdd-2.5.5}/tests/test_cli/test_init.py

@@ -1217,27 +1217,6 @@ class TestInitPiBackend:
                 )
 
 
-def test_module_version_resolves():
-    """Import-time guard: deviate.__version__ must not raise PackageNotFoundError.
-
-    Regression: src/deviate/__init__.py previously called
-    version("deviate") (the import name) instead of "deviatdd" (the
-    distribution name in pyproject.toml), so importing the package failed
-    with PackageNotFoundError and the entire CLI was unreachable.
-    """
-    import importlib
-
-    import deviate
-
-    importlib.reload(deviate)  # force re-evaluation of the module-level call
-    assert deviate.__version__, "deviate.__version__ must be a non-empty string"
-    assert "+unknown" not in deviate.__version__, (
-        f"deviate.__version__ is the missing-metadata fallback: {deviate.__version__!r}. "
-        "Check that the deviatdd distribution is installed (e.g. "
-        "`uv tool install --force .`)."
-    )
-
-
 def test_version():
     """`deviate --version` prints the installed distribution version.
 

deviatdd-2.5.5/tests/test_init.py

@@ -0,0 +1,29 @@
+"""Tests for the top-level `deviate` package.
+
+Mirrors `src/deviate/__init__.py` — the module-level version lookup that
+fires on every `import deviate`. The CLI smoke suite (`test_cli/test_init.py`)
+exercises the same lookup via `deviate --version`; these tests guard the
+import-time contract directly so a regression fails at collection rather
+than at first invocation.
+"""
+
+
+def test_module_version_resolves():
+    """Import-time guard: deviate.__version__ must not raise PackageNotFoundError.
+
+    Regression: src/deviate/__init__.py previously called
+    version("deviate") (the import name) instead of "deviatdd" (the
+    distribution name in pyproject.toml), so importing the package failed
+    with PackageNotFoundError and the entire CLI was unreachable.
+    """
+    import importlib
+
+    import deviate
+
+    importlib.reload(deviate)  # force re-evaluation of the module-level call
+    assert deviate.__version__, "deviate.__version__ must be a non-empty string"
+    assert "+unknown" not in deviate.__version__, (
+        f"deviate.__version__ is the missing-metadata fallback: {deviate.__version__!r}. "
+        "Check that the deviatdd distribution is installed (e.g. "
+        "`uv tool install --force .`)."
+    )

{deviatdd-2.5.3 → deviatdd-2.5.5}/uv.lock

@@ -85,7 +85,7 @@ wheels = [
 
 [[package]]
 name = "deviatdd"
-version = "2.5.3"
+version = "2.5.5"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },