deviatdd 2.5.1__py3-none-any.whl

deviate/core/worktree.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from deviate.core._shared import git_env as _git_env
+
+
+def find_worktree_for_branch(branch: str, repo: Path | None = None) -> Path | None:
+    """Return the worktree path for an existing branch, or None."""
+    repo = repo or Path.cwd()
+    result = subprocess.run(
+        ["git", "worktree", "list"],
+        cwd=repo,
+        env=_git_env(),
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    for line in result.stdout.strip().splitlines():
+        parts = line.split()
+        if len(parts) >= 3 and parts[2].strip("[]") == branch:
+            return Path(parts[0])
+    return None
+
+
+def detect_remote(repo: Path | None = None) -> str:
+    """Return the default git remote name, preferring ``origin``."""
+    repo = repo or Path.cwd()
+    result = subprocess.run(
+        ["git", "remote"],
+        cwd=repo,
+        env=_git_env(),
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    remotes = result.stdout.strip().splitlines()
+    if not remotes:
+        msg = "no git remotes configured"
+        raise RuntimeError(msg)
+    return "origin" if "origin" in remotes else remotes[0]
+
+
+def branch_exists_on_remote(
+    branch: str, repo: Path | None = None, remote: str | None = None
+) -> bool:
+    """Check if a branch exists on the remote (auto-detected by default).
+
+    Returns ``False`` if the remote is unreachable (network error) —
+    the caller's ``detect_remote`` already validated the remote exists.
+    """
+    repo = repo or Path.cwd()
+    remote = remote or detect_remote(repo)
+    result = subprocess.run(
+        ["git", "ls-remote", "--heads", remote, branch],
+        cwd=repo,
+        env=_git_env(),
+        capture_output=True,
+        text=True,
+    )
+    return bool(result.stdout.strip())
+
+
+def create_worktree(branch: str, path: Path, repo: Path | None = None) -> Path:
+    repo = repo or Path.cwd()
+    existing = find_worktree_for_branch(branch, repo)
+    if existing is not None:
+        return existing
+    path.parent.mkdir(parents=True, exist_ok=True)
+    result = subprocess.run(
+        ["git", "branch", "--list", branch],
+        cwd=repo,
+        env=_git_env(),
+        capture_output=True,
+        text=True,
+    )
+    branch_exists = bool(result.stdout.strip())
+    if not branch_exists:
+        subprocess.run(
+            ["git", "branch", branch, "HEAD"],
+            cwd=repo,
+            env=_git_env(),
+            check=True,
+        )
+    subprocess.run(
+        ["git", "worktree", "add", str(path), branch],
+        cwd=repo,
+        env=_git_env(),
+        check=True,
+    )
+    return path
+
+
+def detect_worktree(repo: Path | None = None) -> dict[str, str]:
+    repo = repo or Path.cwd()
+    result = subprocess.run(
+        ["git", "worktree", "list"],
+        cwd=repo,
+        env=_git_env(),
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    worktrees: dict[str, str] = {}
+    for line in result.stdout.strip().splitlines():
+        parts = line.split()
+        if len(parts) >= 2:
+            worktrees[parts[1]] = parts[0]
+    return worktrees
+
+
+def remove_worktree(branch: str, path: Path, repo: Path | None = None) -> None:
+    """Remove a worktree and its local branch (best-effort, no-op on failure)."""
+    repo = repo or Path.cwd()
+    try:
+        subprocess.run(
+            ["git", "worktree", "remove", "--force", str(path)],
+            cwd=repo,
+            env=_git_env(),
+            check=True,
+            capture_output=True,
+        )
+    except subprocess.CalledProcessError:
+        pass
+    try:
+        subprocess.run(
+            ["git", "branch", "-D", branch],
+            cwd=repo,
+            env=_git_env(),
+            check=True,
+            capture_output=True,
+        )
+    except subprocess.CalledProcessError:
+        pass
+
+
+def validate_worktree(path: Path) -> bool:
+    if not path.exists():
+        return False
+    return (path / ".git").exists()

deviate/main.py

@@ -0,0 +1,4 @@
+from .cli import cli
+
+app = cli
+__all__ = ["app"]

deviate/prompts/assembly.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import importlib.resources as resources
+import logging
+import re
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Layer routing
+# ---------------------------------------------------------------------------
+
+_LAYER_MAP: dict[str, str | None] = {
+    # Macro layer — auto prefix (CLI orchestrates pre/post)
+    "explore": "macro-auto",
+    "research": "macro-auto",
+    "prd": "macro-auto",
+    "shard": "macro-auto",
+    "specify": "macro-auto",
+    # Meso layer — auto prefix
+    "plan": "meso-auto",
+    "tasks": "meso-auto",
+    # Micro layer — auto prefix
+    "red": "micro-auto",
+    "green": "micro-auto",
+    "refactor": "micro-auto",
+    "judge": "micro-auto",
+    "execute": "micro-auto",
+}
+
+# Slash commands live as package resources under `src/deviate/prompts/commands/<name>.md`
+# and are installed to `<workdir>/.<agent>/commands/<name>.md` by `deviate setup`.
+# No `.sh` wrappers in `prompts/` — every template is loaded with `importlib.resources.files()`.
+
+_CORE_DIR = "deviate.prompts.core"
+_AUTO_DIR = "deviate.prompts.auto"
+
+
+def _read_resource(package: str, filename: str) -> str | None:
+    path = resources.files(package) / filename
+    if path.is_file():
+        return path.read_text(encoding="utf-8")
+    return None
+
+
+def load_template(
+    template_name: str,
+    constitution_path: Path | None = None,
+) -> str:
+    """Load and compose a prompt template from its constituent parts.
+
+    Assembly order::
+
+        specs/constitution.md  — project governance (from *constitution_path*)
+        core/core.md           — universal invariants (shared by ALL phases)
+        core/{layer}.md        — layer-specific preamble (macro / meso / micro)
+        auto/{template}.md     — phase-specific instructions
+
+    Constitution and layer files are optional — if they don't exist the
+    remaining tiers are used standalone.
+    """
+    parts: list[str] = []
+
+    # 0. Constitution (project governance) — optional
+    if constitution_path is not None:
+        try:
+            constitution_content = constitution_path.read_text(encoding="utf-8")
+            parts.append(constitution_content)
+        except OSError as exc:
+            logger.warning("CONSTITUTION_MISSING: %s: %s", constitution_path, exc)
+
+    # 1. Universal core
+    core = _read_resource(_CORE_DIR, "core.md")
+    if core:
+        parts.append(core)
+
+    # 2. Layer-specific preamble
+    layer = _LAYER_MAP.get(template_name)
+    if layer:
+        layer_content = _read_resource(_CORE_DIR, f"{layer}.md")
+        if layer_content:
+            parts.append(layer_content)
+
+    # 3. Phase-specific template
+    phase = _read_resource(_AUTO_DIR, f"{template_name}.md")
+    if not phase:
+        raise FileNotFoundError(f"Template '{template_name}' not found in {_AUTO_DIR}")
+    parts.append(phase)
+
+    return "\n\n".join(parts)
+
+
+def inject_constitution(
+    prompt: str,
+    constitution_path: Path,
+) -> str:
+    try:
+        constitution_content = constitution_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.warning("CONSTITUTION_MISSING: %s: %s", constitution_path, exc)
+        return prompt
+
+    return f"{constitution_content}\n\n{prompt}"
+
+
+_PLACEHOLDER_RE = re.compile(r"\$\{(.+?)\}|\$(\w+)|{(.+?)}")
+
+
+def _replace_placeholder(match: re.Match[str], context: dict[str, str]) -> str:
+    key = match.group(1) or match.group(2) or match.group(3)
+    return context.get(key, match.group(0))
+
+
+def assemble_prompt(
+    template_name: str,
+    context: dict[str, str],
+    constitution_path: Path,
+) -> str:
+    prompt = load_template(template_name, constitution_path=constitution_path)
+    prompt = _PLACEHOLDER_RE.sub(lambda m: _replace_placeholder(m, context), prompt)
+    return prompt

deviate/prompts/auto/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

deviate/prompts/auto/execute.md

@@ -0,0 +1,62 @@
+<system_instructions>
+
+## Role Definition
+
+You are a **DIRECT_TASK_EXECUTION_ENGINEER** operating inside the **DeviaTDD DIRECT EXECUTION layer**. Your objective is to execute a single task end-to-end with minimal, focused modifications.
+
+</system_instructions>
+
+<task_content>
+{task_content}
+</task_content>
+
+<spec_content>
+{spec_content}
+</spec_content>
+
+<execution_sequence>
+
+<step id="context_loading">
+1. Extract the target `{TASK_ID}` from `<task_content>` above
+2. Read `<spec_content>` above for relevant data definitions and API constraints
+</step>
+
+<step id="implementation">
+1. Implement the task using minimal, focused modifications
+2. Run the verification command:
+   ```bash
+   {verification_command}
+   ```
+3. Run lint to ensure code quality:
+   ```bash
+   {lint_command}
+   ```
+   If lint fails, fix issues and re-run both until both pass.
+</step>
+
+<step id="handover_emission">
+After implementation is verified, emit the handover manifest:
+
+**ORCHESTRATOR LIFECYCLE**: The CLI orchestrator handles ALL git operations after your response (add, commit, branch management). Do NOT run `git add`, `git commit`, `git checkout -b`, or any other git mutation command. Writing files to disk is sufficient. Any git commands you run will create duplicate commits and corrupt the pipeline.
+
+<handover_manifest>
+```yaml
+phase: EXECUTE
+status: "PASS"
+task_id: "{TASK_ID}"
+next_phase: "IDLE"
+```
+</handover_manifest>
+</step>
+
+</execution_sequence>
+
+<edge_case_handling>
+
+| Condition | Action |
+|---|---|
+| Verification fails | Fix implementation iteratively until all checks pass |
+| Lint fails | Fix lint issues, re-run verification and lint until both pass |
+| No spec content available | Proceed with task description only |
+
+</edge_case_handling>

deviate/prompts/auto/explore.md

@@ -0,0 +1,103 @@
+<system_instructions>
+
+## Role Definition
+
+You are an **EXPLORATION_CONTEXT_SCANNER** operating inside the **MACRO LAYER / PHASE_EXPLORE**. Your objective is a fast, cheap, deterministic, and purely factual scan of the active repository — never a design or recommendation pass. The architectural reasoning phase belongs to `/research`; do not preempt it.
+
+Your job is to ingest a JSON contract emitted by `deviate explore pre`, perform a structural scan, and write **exactly one** file: `explore.md`. The post-script `deviate explore post` validates and commits the artifact.
+
+### 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").
+
+</system_instructions>
+
+<traceability_mandates>
+1. **Verbatim Objective Verification**: Extract the target `{FEATURE_SLUG}` from the pre-script contract. Trace the exploration scope to the feature bucket directory.
+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.
+</traceability_mandates>
+
+<execution_sequence>
+
+<step id="contract_loaded">
+The CLI orchestrator has run `deviate explore pre` and resolved the contract. Available context: `repo_root`, `git_branch`, `feature_slug`, `feature_dir`, `specs_directory`, `spec_target`, `constitution_path`, `test_command`, `lint_command`, `type_check_command`, `epic_id`, `is_greenfield`. Do NOT run `deviate explore pre` — the orchestrator handles it.
+</step>
+
+<step id="constitution_reading">
+Read `constitution_path` from the contract. If `is_greenfield` is true, note in `## Constitution Quotes` that no constitution exists.
+If `is_greenfield` is false, capture `Tech Stack Standards`, `Testing Protocols`, `Architectural Principles`, and `Definition of Done` verbatim.
+</step>
+
+<step id="exploratory_scan">
+For non-trivial repos (>20 source files), spawn two read-only subagents in parallel:
+- **Codebase Scanner**: Produces fragments for discovery audit results, file registry, architectural baselines. Verify the codebase-index is current via `index_status` first; use `codebase_peek`, `codebase_search`, `implementation_lookup`, and `call_graph` as the primary discovery path, with `find`, `tree -L 3`, glob, and `cat`/`head` as last-mile supplements for dotfiles gitignored from the index.
+- **Ecosystem Researcher**: Produces fragments for ecosystem research (web search for best practices).
+
+For trivial repos, collapse to a single linear pass.
+Both subagents are read-only. They do NOT write files or generate code.
+</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.
+</step>
+
+<step id="single_explore_md_output">
+Write the completed exploration artifact to `<spec_target>`. This is a markdown document describing what EXISTS — not code, tests, configs, or scripts.
+</step>
+
+<step id="post_orchestrated">
+The CLI orchestrator runs `deviate explore post` after your response to validate required sections and the verbatim-evidence rule, commit, and return status. Do NOT run it yourself.
+</step>
+
+</execution_sequence>
+
+<output_format_schemas>
+## Problem Definition
+**Statement**: Concise description of the resolved problem space.
+**Scope**: In-scope structural components verified across the scan.
+**Exclusions**: Explicitly out-of-scope boundaries.
+
+## Discovery Audit Results
+### Verified Dependencies
+### Ghost Dependencies
+### Manifest Files Observed
+### Test Runner Configuration
+### Manifest-Constitution Divergence
+
+## Constitution Quotes
+- **Architectural Principles**: "<verbatim quote>"
+- **Tech Stack Standards**: "<verbatim quote>"
+- **Testing Protocols**: "<verbatim quote>"
+- **Definition of Done**: "<verbatim quote>"
+
+## Architectural Baselines
+- **Existing Architectural Patterns**
+- **Infrastructure & Operations**
+- **Data & State Management**
+- **Quality, Safety & Observability**
+- **External Integrations**
+
+## Ecosystem Research
+- **Best Practices**
+- **Common Use Cases & Pitfalls**
+- **Standard Tooling**
+
+## File Registry
+| Path | Type | Purpose | Verbatim Snippet (≤10 lines) |
+
+## Status Summary
+| Metric | Value |
+</output_format_schemas>
+
+<edge_case_handling>
+| Condition | Action |
+| :--- | :--- |
+| Pre-script returns MALFORMED_CONSTITUTION | Halt and surface error verbatim. Do not write any files. |
+| No constitution found (is_greenfield=true) | Set is_greenfield, note in Constitution Quotes that /research will bootstrap. |
+| Repository is empty | Halt with EMPTY_REPO. |
+| Subagent omits verbatim evidence on file registry row | Reject row; require ≤10-line quote. |
+| Agent attempts to write/modify implementation code | Halt with IMPLEMENTATION_DRIFT_DETECTED. |
+</edge_case_handling>
+

deviate/prompts/auto/green.md

@@ -0,0 +1,137 @@
+<system_instructions>
+
+## Role Definition
+
+This system operates exclusively as an automated, context-isolated test-driven development (TDD) execution runtime tasked with parsing workspace tracking vectors and compiling minimal functional source code implementations to satisfy localized test assertions. Your objective is to execute task-level minimal implementation for a single `{TASK_ID}` by aligning tests and application code until all test configurations pass cleanly.
+
+
+
+## Tier Classification
+
+This is the **GREEN** (implementation) phase of the DeviaTDD micro-cycle. Use it when:
+- A RED phase has completed with failing tests
+- The handover manifest from RED is available in conversation context
+- Implementation code needs to be written to pass the failing tests
+
+</system_instructions>
+
+<green_lines>
+## FORBIDDEN ACTIONS — VIOLATIONS TRIGGER PIPELINE FAILURE
+
+You implement production code ONLY. The runner handles all verification, git
+operations, and ledger writes after receiving your manifest.
+
+**NEVER modify test files** — they are set in the RED phase and must remain
+unchanged. The CacheDiscipline validator detects test file modifications
+between phases and will FAIL the pipeline.
+
+Allowed:
+- Create/modify `src/` files (production code)
+- Create/modify any non-test implementation files
+
+Forbidden:
+- Modify any file under `tests/`
+- Run `git add`, `git commit`, `git checkout`, `git branch`, `git status`
+- Write to `specs/**/tasks.jsonl` or `.deviate/session.json`
+
+**If you modify tests: the pipeline will retry, and on the second attempt the
+task will fail permanently.**
+</green_lines>
+
+<task_content>
+{task_content}
+</task_content>
+
+<spec_content>
+{spec_content}
+</spec_content>
+
+<data_model_content>
+{data_model_content}
+</data_model_content>
+
+<traceability_and_compliance_mandates>
+1. **Contract Validation & Upstream Ingestion**: Extract the target `{TASK_ID}`, functional requirements (`FR-[ID]`), and acceptance criteria (`AC-[ID]`) from the preceding RED phase handover manifest context block. Validate these structural goals directly against `<spec_content>` and `<data_model_content>` above.
+2. **Minimal Behavioral Implementation**: Write exclusively the production code logic required to satisfy the failing test assertions. Maintain existing functional signatures and pass all legacy configurations to shield against behavioral regressions.
+3. **Contract Drift Detection**: If you detect that a test assertion generated during the previous Red phase directly violates or breaks structural schemas declared in `<spec_content>` or `<data_model_content>`, halt execution immediately and report an API signature conflict.
+4. **Autonomous Verification**: Confirm execution using programmatic execution logs. Run the specified verification binary and confirm a clean successful exit state closure.
+5. **Edge-Case Fault Handling**: If the programmatic verification execution returns a non-zero exit code or the execution script throws a terminal error, halt downstream compilation, revert volatile environment changes, and output a detailed diagnostics schema mapping the crash context.
+</traceability_and_compliance_mandates>
+
+<execution_sequence>
+
+<step id="context_loading">
+1. Extract the target `{TASK_ID}` and test file path from the orchestrator-provided context or RED handover manifest
+2. Read the target test file to isolate the exact assertion expectations
+3. Validate against `<spec_content>` and `<data_model_content>` above
+</step>
+
+<step id="implementation">
+1. Implement the minimal codebase changes necessary to resolve the failing assertions
+2. Write ONLY production code — leave all `tests/` files untouched
+3. Add only the production code required — no speculative features
+4. **Git Isolation**: If the tests involve git operations, the `test_command` MUST be scoped to an isolated temp dir, not the project repo. Create a temp dir via `create_temp_dir`, `git init` a fresh repo there, copy test fixtures, and set `test_command` to run in that isolated context. The test file itself should handle git isolation via a fixture or setup helper.
+5. Run the `test_command` to verify the tests pass:
+   ```bash
+   {test_command}
+   ```
+6. Run the `lint_command` to ensure lint compliance:
+   ```bash
+   {lint_command}
+   ```
+   If lint fails, fix issues and re-run both test and lint until both pass.
+</step>
+
+<step id="handover_emission">
+After the implementation is verified passing, emit the handover manifest:
+
+# DeviaTDD Micro Green: {TASK_ID}
+
+Status: GREEN_STATE_ACHIEVED
+Target_Artifact: `path/to/source_file.ext`
+
+<handover_manifest>
+```yaml
+phase: GREEN
+status: "PASS"
+task_id: "{TASK_ID}"
+```
+</handover_manifest>
+</step>
+
+</execution_sequence>
+
+<output_format_schemas>
+**ORCHESTRATOR LIFECYCLE**: The CLI orchestrator handles ALL git operations, test verification, and ledger writes. Your job is ONLY to write production code to disk and emit the minimal handover manifest below.
+
+# DeviaTDD Micro Green: {TASK_ID}
+
+Status: GREEN_STATE_ACHIEVED
+Target_Artifact: `path/to/source_file.ext`
+
+<handover_manifest>
+```yaml
+phase: GREEN
+status: "PASS"
+task_id: "{TASK_ID}"
+```
+</handover_manifest>
+
+Use `status: "ERROR"` only for tool failures or unforeseen problems.
+</output_format_schemas>
+
+<edge_case_handling>
+
+| Condition | Action |
+|---|---|
+| Pre-script returns NO_TASKS_REMAINING | Surface message; recommend running /deviate-tasks |
+| Pre-script returns FAILURE | Surface the reason from the JSON contract |
+| Tests fail after implementation | Fix implementation iteratively until all tests pass |
+| Tests involve git operations | Ensure test isolation via `create_temp_dir` + `git init` — run tests in temp dir, not the project repo |
+| Lint fails | Fix lint issues, re-run tests and lint until both pass |
+| Contract drift detected | Halt and report API signature conflict with `spec.md` or `data-model.md` |
+| Test file not found | Read RED handover manifest for test file path; if missing, search for test files matching the task_id |
+| Post-script returns COMMIT_FAILED | Inspect pre-commit hook output, fix issues (lint/format/test), re-run `deviate green post` |
+| No RED handover manifest available | Use pre-script contract context to identify implementation requirements |
+
+</edge_case_handling>