deviatdd 2.5.1__py3-none-any.whl

deviate/prompts/core/micro-auto.md

@@ -0,0 +1,76 @@
+<micro_layer_model>
+
+NOTE: This differs from ``micro-skill.md`` — the ``-auto`` variants reference the CLI orchestrator,
+while ``-skill`` variants reference the pre/post scripts directly, because skill prompts are invoked
+by the agent directly (agent runs pre/post) while auto prompts are orchestrated by the CLI.
+
+This phase operates inside the **MICRO LAYER** — the Red-Green-Refactor cycle for individual tasks.
+
+<rgr_cycle>
+
+Each task is a Logical Unit (30-90 min) that undergoes ONE complete R-G-R cycle:
+
+<item>
+**RED**: Write a failing test — verified to fail due to missing implementation, not syntax errors.
+</item>
+
+<item>
+**GREEN**: Write the minimum production code to pass the test.
+</item>
+
+<item>
+**REFACTOR**: Behavior-preserving structural cleanup without modifying tests.
+</item>
+
+</rgr_cycle>
+
+<shared_disciplines>
+
+<item>
+<title>Test-First Discipline</title>
+No production code is written before a failing test exists. Tests are the executable specification — the RED phase verifies the test fails before GREEN begins.
+</item>
+
+<item>
+<title>Sociable Tests Over Solitary</title>
+Prefer sociable (integration) tests that exercise real component orchestration. Restrict mocking exclusively to non-deterministic external networks, third-party transactional interfaces, or volatile system attributes (system epoch timers, cryptographic entropy paths).
+</item>
+
+<item>
+<title>Verification-is-Done</title>
+A task is ONLY finished when its `Verification` command passes. Verification is deterministic and scoped — run the specific test file, not the entire suite.
+</item>
+
+<item>
+<title>Git Isolation</title>
+Any test that invokes git operations MUST operate on an isolated temporary directory initialized as a fresh git repo. Tests MUST NOT run git commands within the real project repository. Use `create_temp_dir` → `git init` → copy fixtures → run test in that context.
+</item>
+
+<item>
+<title>Orchestrator Lifecycle</title>
+The CLI orchestrator handles all pre/post lifecycle — it injects context, stages files, runs pre-commit hooks, updates the task ledger, and commits. Do NOT run `deviate <phase> pre/post` or use `git add`/`git commit` directly.
+</item>
+
+<item>
+<title>YAML Quoting Rule</title>
+ALL string values in the handover manifest YAML MUST be wrapped in double quotes. A value containing a colon (`:`) will BREAK YAML parsing if unquoted.
+</item>
+
+<item>
+<title>Flow-Anchored Implementation</title>
+Micro phases are where Product-layer context is at the highest risk of being lost. Every micro phase MUST (a) read the active task's `**Flow References**` field from `tasks.md` before writing any code, (b) restate the user-visible flow(s) the task serves in the handover manifest under `flow_refs`, and (c) verify the test or implementation exercises behavior derivable from those flows — not implementation details detached from user intent. **judge** MUST add a `flow_alignment` rubric dimension alongside Spec Compliance: does the diff preserve or extend the flows named in the task's `**Flow References**`? A change that silently abandons or breaks a named flow MUST fail JUDGE with severity HIGH and a `train_feedback` block instructing the next GREEN attempt to re-anchor to the flow. **red** MUST write tests that describe user-visible behavior derivable from the parent flow's Trigger and Happy Path, not internal function signatures. **green** MUST implement the minimum production code to satisfy those flow-anchored tests, restricting scope to workstation files explicitly tied to the named flow. **refactor**, **yellow**, and **execute** inherit the same flow context and MUST NOT extend scope beyond what the named flow requires. If `tasks.md` carries `**Flow References**: []`, treat the task as enabling/infrastructure (no flow anchor required) but still surface the empty list in the handover manifest.
+</item>
+
+</shared_disciplines>
+
+</micro_layer_model>
+
+<mandate>
+STDOUT OUTPUT MANDATE: Your final stdout response must be EXACTLY the YAML block from the `<handover_manifest>` section. No conversational text, no analysis, no commentary, no markdown formatting, no file content on stdout. Write artifact files to their target paths only (not to stdout). The caller parses your stdout as raw YAML.
+</mandate>
+
+<context>
+<user_input>
+$ARGUMENTS
+</user_input>
+</context>

deviate/prompts/core/micro-command.md

@@ -0,0 +1,67 @@
+<micro_layer_model>
+
+This phase operates inside the **MICRO LAYER** — the Red-Green-Refactor cycle for individual tasks.
+
+<rgr_cycle>
+
+Each task is a Logical Unit (30-90 min) that undergoes ONE complete R-G-R cycle:
+
+<item>
+**RED**: Write a failing test — verified to fail due to missing implementation, not syntax errors.
+</item>
+
+<item>
+**GREEN**: Write the minimum production code to pass the test.
+</item>
+
+<item>
+**REFACTOR**: Behavior-preserving structural cleanup without modifying tests.
+</item>
+
+</rgr_cycle>
+
+<shared_disciplines>
+
+<item>
+<title>Test-First Discipline</title>
+No production code is written before a failing test exists. Tests are the executable specification — the RED phase verifies the test fails before GREEN begins.
+</item>
+
+<item>
+<title>Sociable Tests Over Solitary</title>
+Prefer sociable (integration) tests that exercise real component orchestration. Restrict mocking exclusively to non-deterministic external networks, third-party transactional interfaces, or volatile system attributes (system epoch timers, cryptographic entropy paths).
+</item>
+
+<item>
+<title>Verification-is-Done</title>
+A task is ONLY finished when its `Verification` command passes and the post-script commits successfully. Verification is deterministic and scoped — run the specific test file, not the entire suite.
+</item>
+
+<item>
+<title>Git Isolation</title>
+Any test that invokes git operations MUST operate on an isolated temporary directory initialized as a fresh git repo. Tests MUST NOT run git commands within the real project repository. Use `create_temp_dir` → `git init` → copy fixtures → run test in that context.
+</item>
+
+<item>
+<title>Post-Script Protocol</title>
+Every micro phase ends with `deviate <phase> post`. This is MANDATORY — do NOT use `git add` / `git commit` directly. The post-script stages files, runs pre-commit hooks (lint, format-check, tests), updates the task ledger, and commits. Allocate a timeout of at least 180s (3 minutes) for post-script execution.
+</item>
+
+<item>
+<title>Handover Manifest YAML</title>
+After post-script success, emit a handover manifest as a YAML code block. ALL string values MUST be wrapped in double quotes. A value containing a colon (`:`) will BREAK YAML parsing if unquoted. Output NOTHING outside the YAML block — no explanations, no commentary.
+</item>
+
+<item>
+<title>Offline Documentation Guidance</title>
+When implementing, use `libref query <library> <topic>` to look up library APIs and framework conventions. The `libref` CLI provides offline, version-pinned documentation — prefer it over web fetching. If `libref` is unavailable, fall back to training data or web fetch.
+</item>
+
+<item>
+<title>Flow-Anchored Implementation</title>
+Micro phases are where Product-layer context is at the highest risk of being lost. Every micro phase MUST (a) read the active task's `**Flow References**` field from `tasks.md` before writing any code, (b) restate the user-visible flow(s) the task serves in the handover manifest under `flow_refs`, and (c) verify the test or implementation exercises behavior derivable from those flows — not implementation details detached from user intent. **judge** MUST add a `flow_alignment` rubric dimension alongside Spec Compliance: does the diff preserve or extend the flows named in the task's `**Flow References**`? A change that silently abandons or breaks a named flow MUST fail JUDGE with severity HIGH and a `train_feedback` block instructing the next GREEN attempt to re-anchor to the flow. **red** MUST write tests that describe user-visible behavior derivable from the parent flow's Trigger and Happy Path, not internal function signatures. **green** MUST implement the minimum production code to satisfy those flow-anchored tests, restricting scope to workstation files explicitly tied to the named flow. **refactor**, **yellow**, and **execute** inherit the same flow context and MUST NOT extend scope beyond what the named flow requires. If `tasks.md` carries `**Flow References**: []`, treat the task as enabling/infrastructure (no flow anchor required) but still surface the empty list in the handover manifest.
+</item>
+
+</shared_disciplines>
+
+</micro_layer_model>

deviate/prompts/core/micro-skill.md

@@ -0,0 +1,67 @@
+<micro_layer_model>
+
+This phase operates inside the **MICRO LAYER** — the Red-Green-Refactor cycle for individual tasks.
+
+<rgr_cycle>
+
+Each task is a Logical Unit (30-90 min) that undergoes ONE complete R-G-R cycle:
+
+<item>
+**RED**: Write a failing test — verified to fail due to missing implementation, not syntax errors.
+</item>
+
+<item>
+**GREEN**: Write the minimum production code to pass the test.
+</item>
+
+<item>
+**REFACTOR**: Behavior-preserving structural cleanup without modifying tests.
+</item>
+
+</rgr_cycle>
+
+<shared_disciplines>
+
+<item>
+<title>Test-First Discipline</title>
+No production code is written before a failing test exists. Tests are the executable specification — the RED phase verifies the test fails before GREEN begins.
+</item>
+
+<item>
+<title>Sociable Tests Over Solitary</title>
+Prefer sociable (integration) tests that exercise real component orchestration. Restrict mocking exclusively to non-deterministic external networks, third-party transactional interfaces, or volatile system attributes (system epoch timers, cryptographic entropy paths).
+</item>
+
+<item>
+<title>Verification-is-Done</title>
+A task is ONLY finished when its `Verification` command passes and the post-script commits successfully. Verification is deterministic and scoped — run the specific test file, not the entire suite.
+</item>
+
+<item>
+<title>Git Isolation</title>
+Any test that invokes git operations MUST operate on an isolated temporary directory initialized as a fresh git repo. Tests MUST NOT run git commands within the real project repository. Use `create_temp_dir` → `git init` → copy fixtures → run test in that context.
+</item>
+
+<item>
+<title>Post-Script Protocol</title>
+Every micro phase ends with `deviate <phase> post`. This is MANDATORY — do NOT use `git add` / `git commit` directly. The post-script stages files, runs pre-commit hooks (lint, format-check, tests), updates the task ledger, and commits. Allocate a timeout of at least 180s (3 minutes) for post-script execution.
+</item>
+
+<item>
+<title>Handover Manifest YAML</title>
+After post-script success, emit a handover manifest as a YAML code block. ALL string values MUST be wrapped in double quotes. A value containing a colon (`:`) will BREAK YAML parsing if unquoted. Output NOTHING outside the YAML block — no explanations, no commentary.
+</item>
+
+<item>
+<title>Offline Documentation Guidance</title>
+When implementing, use `libref query <library> <topic>` to look up library APIs and framework conventions. The `libref` CLI provides offline, version-pinned documentation — prefer it over web fetching. If `libref` is unavailable, fall back to training data or web fetch.
+</item>
+
+<item>
+<title>Flow-Anchored Implementation</title>
+Micro phases are where Product-layer context is at the highest risk of being lost. Every micro phase MUST (a) read the active task's `**Flow References**` field from `tasks.md` before writing any code, (b) restate the user-visible flow(s) the task serves in the handover manifest under `flow_refs`, and (c) verify the test or implementation exercises behavior derivable from those flows — not implementation details detached from user intent. **judge** MUST add a `flow_alignment` rubric dimension alongside Spec Compliance: does the diff preserve or extend the flows named in the task's `**Flow References**`? A change that silently abandons or breaks a named flow MUST fail JUDGE with severity HIGH and a `train_feedback` block instructing the next GREEN attempt to re-anchor to the flow. **red** MUST write tests that describe user-visible behavior derivable from the parent flow's Trigger and Happy Path, not internal function signatures. **green** MUST implement the minimum production code to satisfy those flow-anchored tests, restricting scope to workstation files explicitly tied to the named flow. **refactor**, **yellow**, and **execute** inherit the same flow context and MUST NOT extend scope beyond what the named flow requires. If `tasks.md` carries `**Flow References**: []`, treat the task as enabling/infrastructure (no flow anchor required) but still surface the empty list in the handover manifest.
+</item>
+
+</shared_disciplines>
+
+</micro_layer_model>

deviate/prompts/extras/deviate-pr-graphite-routing.md

@@ -0,0 +1,20 @@
+<graphite_routing>
+When Graphite is enabled (`.deviate/config.toml` has `graphite = true`), this skill routes PR operations through the Graphite CLI (`gt`) instead of the GitHub CLI (`gh`).
+
+<pr_submission>
+- Use `gt submit --stack --no-edit` to submit the entire stacked branch for review.
+- After `gt submit --stack`, the `deviate pr run` command calls `_update_gt_prs()` in `src/deviate/cli/meso.py:959` which parses the submit output for PR URLs and runs `gh pr edit <number> --title <title> --body-file <path>` on each created PR. This is because `gt submit` has no `--title` or `--body-file` flag — `gh pr edit` post-submit is the only non-interactive fixup path.
+- Do NOT invoke `gh pr create` directly — Graphite owns PR creation from stacked branches.
+- The `--merge` and `--auto-merge` flags are incompatible with `gt submit --stack` and will be ignored at runtime; surface a warning if they were requested.
+</pr_submission>
+
+<branch_creation_between_tasks>
+When `graphite = true` and the micro layer runs all tasks via `_run_all()` in `src/deviate/cli/micro.py:1854`, it calls `gt create -m "feat(<next_id>): <description>"` after each successful task (except the last) to create a stacked branch for the next task. This ensures each task lands on its own branch in the Graphite stack.
+</branch_creation_between_tasks>
+
+<anti_patterns>
+- Do NOT call `git checkout -b` to create the issue branch — `gt create -am` was already used by the meso layer.
+- Do NOT mix `gh` and `gt` commands in the same PR lifecycle — pick one based on the config flag.
+- Do NOT skip the Graphite routing even if the user requests `gh pr create` manually — defer to the runtime config.
+</anti_patterns>
+</graphite_routing>

deviate/prompts/governance/agents_seed.md

@@ -0,0 +1 @@
+<!-- Intentionally empty: the DeviaTDD Phase Architecture block was project-internal guidance that did not help consuming projects. Removed 2026-06-28. -->

deviate/prompts/governance/claudemd_seed.md

@@ -0,0 +1 @@
+<!-- Intentionally empty: the DeviaTDD Phase Architecture block was project-internal guidance that did not help consuming projects. Removed 2026-06-28. -->

deviate/prompts/governance/graphite_seed.md

@@ -0,0 +1,18 @@
+## Graphite Stacked Changes Workflow
+
+When Graphite integration is enabled (`.deviate/config.toml` contains `graphite = true`):
+
+### Branch Creation
+- Use `gt create -am "<message>"` to create a branch with an automatic commit
+- If the working tree is clean, use `gt create -m "<message>"` instead
+
+### PR Submission
+- Use `gt submit --stack` to submit the entire stack for review
+
+### Syncing
+- Use `gt sync` to sync your stack with the remote
+
+### Anti-Patterns
+- Do NOT use `git checkout -b` alongside `gt` — it bypasses Graphite's stack tracking
+- Do NOT use `gh pr create` when Graphite is enabled — use `gt submit --stack`
+- Do NOT run `gt` commands outside a Graphite-tracked repository

deviate/prompts/governance/libref_seed.md

@@ -0,0 +1,3 @@
+## 📚 Offline Documentation (libref)
+
+Prefer `libref query <lib> "<topic>"` over web fetching. Workflow: `libref list` → `libref query` → `libref add <git-url>` (register a missing source) → web fetch (last resort).

deviate/state/config.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+import json
+import tomllib
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class AgentConfig(BaseModel):
+    # Agent backend: "opencode", "claude", "droid", "pi", or "omp"
+    backend: Literal["opencode", "claude", "droid", "pi", "omp"] = "opencode"
+    # Agent invocation timeout in seconds (must be > 0)
+    timeout: int = Field(default=600, gt=0)
+    # Opt-in RPC mode for Pi — spawns `pi --mode rpc --no-session` instead of `pi -p`
+    pi_rpc: bool = Field(
+        default=False,
+        description="Opt-in RPC mode for Pi (spawns pi --mode rpc --no-session instead of pi -p)",
+    )
+
+    model_config = {"extra": "forbid"}
+
+
+_VALID_PHASES = frozenset(
+    {
+        "IDLE",
+        "EXPLORE",
+        "RESEARCH",
+        "PRD",
+        "SHARD",
+        "SPECIFY",
+        "PLAN",
+        "TASKS",
+        "RED",
+        "GREEN",
+        "JUDGE",
+        "REFACTOR",
+        "E2E",
+        "EXECUTE",
+        "HOTFIX",
+    }
+)
+
+_PHASE_ARTIFACT_MAP: dict[str, tuple[str, ...]] = {
+    "RESEARCH": ("explore.md",),
+    "PRD": ("design.md", "data-model.md"),
+    "SHARD": ("prd.md",),
+    "SPECIFY": ("spec.md",),
+    "PLAN": ("plan.md",),
+    "TASKS": ("spec.md", "tasks.md"),
+}
+
+
+class TransitionViolationError(Exception):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Module-level utility functions (extracted from SessionState static methods)
+# ---------------------------------------------------------------------------
+
+
+def validate_filesystem_state(
+    phase: str,
+    epic_slug: str | None,
+    repo_path: Path,
+) -> list[str]:
+    expected_artifacts = _PHASE_ARTIFACT_MAP.get(phase, ())
+    missing: list[str] = []
+    for artifact in expected_artifacts:
+        artifact_path = (
+            repo_path / "specs" / epic_slug / artifact
+            if epic_slug
+            else repo_path / artifact
+        )
+        if not artifact_path.exists():
+            missing.append(artifact)
+    return missing
+
+
+def reconstruct_from_worktree(worktree: Path) -> SessionState:
+    has_spec = (worktree / "spec.md").exists()
+    has_plan = (worktree / "plan.md").exists()
+    has_tasks = (worktree / "tasks.md").exists()
+    if has_plan and has_tasks:
+        phase = "TASKS"
+    elif has_plan:
+        phase = "PLAN"
+    elif has_spec and has_tasks:
+        phase = "TASKS"
+    elif has_spec:
+        phase = "SPECIFY"
+    else:
+        phase = "IDLE"
+    return SessionState(current_phase=phase)
+
+
+def normalize_task_id(ref: str) -> str:
+    return ref.rstrip(":")
+
+
+class DeviateConfig(BaseModel):
+    # Profile name — defines preset config groups (default, full, fast, secure)
+    profile: str = "default"
+    # CLI inactivity timeout in seconds (must be > 0)
+    timeout_seconds: int = Field(default=300, gt=0)
+    # Agent export mode: "local" (project .claude/) or "global" (~/.claude/)
+    agent_export_mode: Literal["local", "global"] = "local"
+    # Agent backend config (opencode, claude, or droid)
+    agent: AgentConfig = Field(default_factory=AgentConfig)
+    # Per-phase model overrides, e.g. default = "opencode/deepseek-v4-flash"
+    models: dict[str, str] = Field(default_factory=dict)
+    # Enable the libref CLI for offline documentation lookups
+    use_libref: bool = False
+    # Enable Graphite CLI integration for stacked changes
+    graphite: bool = Field(default=False)
+
+    model_config = {"extra": "forbid"}
+
+
+def _load_deviate_config_toml(root: Path) -> dict | None:
+    """Load the `.deviate/config.toml` file, returning a dict or None."""
+    config_path = root / ".deviate" / "config.toml"
+    if not config_path.exists():
+        return None
+    try:
+        with open(config_path, "rb") as f:
+            return tomllib.load(f)
+    except Exception:
+        return None
+
+
+def resolve_phase_model(phase: str, models: dict[str, str]) -> str | None:
+    """Resolve the model ID for *phase* from a `[models]` dict.
+
+    Resolution order (case-insensitive):
+        1. Phase-specific key (e.g. ``judge``, ``plan``, ``red``)
+        2. ``default`` key
+        3. ``None`` — backend falls back to its native default
+    """
+    if not models:
+        return None
+    phase_lower = phase.lower()
+    lookup = {k.lower(): val for k, val in models.items() if val}
+    if phase_lower in lookup:
+        return lookup[phase_lower]
+    if "default" in lookup:
+        return lookup["default"]
+    return None
+
+
+def resolve_model_for_phase(phase: str, root: Path) -> str | None:
+    """Load `[models]` from `.deviate/config.toml` and resolve *phase*.
+
+    Backed by :func:`resolve_phase_model`. ``opencode`` and ``droid``
+    backends accept ``--model <id>``; the ``claude`` backend ignores the
+    resolved value silently.
+    """
+    data = _load_deviate_config_toml(root)
+    if data is None:
+        return None
+    models = data.get("models", {})
+    if not isinstance(models, dict):
+        return None
+    return resolve_phase_model(phase, {k: str(v) for k, v in models.items()})
+
+
+def resolve_graphite_config(root: Path) -> bool:
+    """Check whether the Graphite integration is enabled in `.deviate/config.toml`."""
+    data = _load_deviate_config_toml(root)
+    if data is None:
+        return False
+    value = data.get("graphite", False)
+    return value if isinstance(value, bool) else False
+
+
+class PytestReportConfig(BaseModel):
+    json_report: bool = False
+
+    model_config = {"extra": "forbid"}
+
+
+class ProfileConfig(BaseModel):
+    default: Literal["full", "fast", "secure"] = "full"
+
+    model_config = {"extra": "forbid"}
+
+    def to_toml_string(self) -> str:
+        return 'default = "{}"\n'.format(self.default)
+
+
+class SessionState(BaseModel):
+    current_phase: str = "IDLE"
+    active_issue_id: Optional[str] = None
+    last_command: str = ""
+    train_feedback: str = ""
+    judge_rejected: bool = False
+    red_commit_sha: str = ""
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @field_validator("current_phase")
+    @classmethod
+    def _validate_phase(cls, v: str) -> str:
+        if v not in _VALID_PHASES:
+            valid = ", ".join(sorted(_VALID_PHASES))
+            raise ValueError(f"Invalid phase '{v}'. Must be one of: {valid}")
+        return v
+
+    def transition_to(self, phase: str) -> SessionState:
+        return SessionState(
+            current_phase=phase,
+            active_issue_id=self.active_issue_id,
+            last_command=self.last_command,
+            red_commit_sha=self.red_commit_sha,
+            timestamp=datetime.now(timezone.utc),
+        )
+
+    def force_transition_to(self, phase: str) -> SessionState:
+        return SessionState(
+            current_phase=phase,
+            active_issue_id=self.active_issue_id,
+            last_command=self.last_command,
+            red_commit_sha=self.red_commit_sha,
+            train_feedback=self.train_feedback,
+            judge_rejected=self.judge_rejected,
+            timestamp=datetime.now(timezone.utc),
+        )
+
+    def save(self, path: Path) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(self.model_dump_json(indent=2), encoding="utf-8")
+
+    @classmethod
+    def load(cls, path: Path) -> SessionState:
+        if not path.exists():
+            return cls()
+        raw = path.read_text(encoding="utf-8")
+        data = json.loads(raw)
+        return cls.model_validate(data)
+
+    @staticmethod
+    def validate_filesystem_state(
+        phase: str,
+        epic_slug: str | None,
+        repo_path: Path,
+    ) -> list[str]:
+        return validate_filesystem_state(phase, epic_slug, repo_path)
+
+    @staticmethod
+    def reconstruct_from_worktree(worktree: Path) -> SessionState:
+        return reconstruct_from_worktree(worktree)
+
+    @staticmethod
+    def normalize_task_id(ref: str) -> str:
+        return normalize_task_id(ref)