deviatdd 2.5.1__py3-none-any.whl

deviate/prompts/commands/deviate-pr.md

@@ -0,0 +1,144 @@
+---
+name: deviate-pr
+description: Create a PR from the current worktree branch; on merge, append COMPLETED to specs/issues.jsonl to unblock dependents.
+category: deviatdd-meso-layer
+version: 1.0.0
+aliases:
+  - pr
+  - /deviate-pr
+  - tools:pr
+---
+
+<system_instructions>
+
+This skill operates as the final gate in the Specify-Tasks-TDD meso workflow. It handles the pull request lifecycle:
+1. Creates a PR from the current worktree branch
+2. Optionally merges directly (if `--merge` is specified)
+3. On successful PR creation, appends a COMPLETED event to `specs/issues.jsonl` — regardless of whether the PR was merged
+4. This natively unblocks dependent issues via the existing `blocked_by` logic in the ledger
+
+CRITICAL INVARIANTS:
+1. **Ledger Update Rule**: Append COMPLETED event after PR is successfully created (not only after merge). The event format: `{"issue_id":"ISS-XXX","status":"COMPLETED","timestamp":"..."}`
+2. **Worktree Context**: The script runs from within the worktree. Use `find_repo_root` to locate the main repo and ledger.
+3. **Idempotency**: If the issue already has a COMPLETED event, do not append a duplicate.
+4. **GitHub CLI Required**: Requires `gh` for PR operations. If unavailable, surface clear error.
+
+</system_instructions>
+
+
+<execution_sequence>
+1. Run the pre-script to validate the worktree state, discover the issue ID, and emit a JSON contract:
+   ```
+   deviate pr pre
+   ```
+   The contract on stdout contains: `issue_id`, `branch_name`, `worktree_path`, `repo_root`, `pr_url` (if PR exists), `ledger_path`, `can_merge` (boolean), plus body generation data: `commit_titles` (pipe-separated), `changed_files` (comma-separated), `diff_summary`, `issue_title`, `base_branch`.
+
+2. **Generate PR Body**. Using the pre-phase data, write a PR body following `<pr_body_format>`.
+   - Read `spec.md` and `tasks.md` from the spec directory (if they exist) for richer context
+   - The body MUST serve dual purpose: good PR description AND good squash-merge commit body
+   - The script will write the body to `pr_descriptions/<branch>.md`, commit, and push it
+
+3. **HITL: Confirm PR creation/merge**. Present the PR details AND generated body to the stakeholder:
+    - If no PR exists: "Create PR for issue {issue_id} on branch {branch_name}?" — show the generated body
+    - If PR exists: "PR #{number} exists. Merge and mark issue COMPLETED?"
+    Use the AskUser tool to present options.
+
+4. Run the main script to create/merge PR and update ledger:
+    ```
+    deviate pr run --body-file <path> [--merge] [--auto-merge]
+    ```
+    Options:
+    - `--body-file <path>`: Path to the PR body file generated in step 2 (required when creating a new PR)
+    - `--merge`: Merge the PR after creation (requires merge permissions)
+    - `--auto-merge`: Enable auto-merge on GitHub (PR merges when checks pass)
+    - Without merge flags: Only create the PR, do not merge
+
+5. The script will:
+    - Create PR using the provided body file (or auto-generate if --body-file omitted)
+    - Merge PR if `--merge` or `--auto-merge` specified
+    - On successful merge, append COMPLETED event to ledger
+    - Emit final status JSON
+
+</execution_sequence>
+
+<output_format_schemas>
+<format_contract>
+The script emits JSON on stdout with the following structure:
+
+Pre-phase contract:
+{
+  "status": "READY|FAILURE",
+  "phase": "pr",
+  "issue_id": "ISS-XXX",
+  "branch_name": "feat/...",
+  "worktree_path": "/absolute/path/to/worktree",
+  "repo_root": "/absolute/path/to/repo",
+  "pr_url": "https://github.com/.../pull/123",
+  "pr_number": 123,
+  "ledger_path": "/absolute/path/to/specs/issues.jsonl",
+  "can_merge": true,
+  "commit_titles": "feat: add X|fix: resolve Y",
+  "changed_files": "src/a.ts,src/b.ts,docs/c.md",
+  "diff_summary": "5 files changed, 100 insertions(+), 50 deletions(-)",
+  "issue_title": "Issue title from ledger",
+  "base_branch": "main",
+  "timestamp": "2026-06-06T12:00:00Z"
+}
+
+Run-phase contract (on success):
+{
+  "status": "SUCCESS",
+  "phase": "pr",
+  "issue_id": "ISS-XXX",
+  "pr_number": 123,
+  "pr_url": "https://github.com/.../pull/123",
+  "merged": true,
+  "ledger_updated": true,
+  "next_action": "Run /deviate-tasks for next unblocked issue",
+  "timestamp": "2026-06-06T12:00:00Z"
+}
+</format_contract>
+</output_format_schemas>
+
+<pr_title_format>
+PR title is generated by the deviate CLI as a conventional commit:
+
+`{type}({issue_id}): {description}`
+
+- **type**: mapped from the issue record's `type` field: `feature → feat`, `bug → fix`, `chore → chore`, `refactor → refactor`, `docs → docs`, default → `feat`
+- **issue_id**: e.g. `ISS-001-005`
+- **description**: the raw issue title with any bracketed prefix (e.g. `[FR-NNN]`) stripped
+
+Examples:
+- `feat(ISS-001-005): CLI Architecture Realignment & Skill Integration`
+- `chore(ISS-002-002): close ISS-002-002 and remove deviate-context skill`
+- `fix(ISS-003-001): handle null pointer in user lookup`
+
+This format ensures the squash-merge commit reads cleanly as a conventional commit subject.
+</pr_title_format>
+
+<pr_body_format>
+The PR body MUST serve dual purpose: a good PR description AND a good squash-merge commit body.
+Use the same structure as tools-pr:
+
+```markdown
+{SUMMARY}
+
+{CHANGES}
+
+{CLOSES}
+```
+
+Summary: 2-4 sentences. Problem-led: what problem does this solve and why.
+Synthesize from commit titles, issue context, and spec — do NOT just concatenate commit messages.
+Changes: grouped by logical concern with file refs inline (e.g., "Migration: removed all `.tex` files and `awesome-cv.cls`").
+NEVER list every file individually — group by directory or concern.
+Closes: `Closes #N` footer when issue number is known. Omit entirely if no issue.
+Omit empty sections. No decorative headers or horizontal rules.
+</pr_body_format>
+
+<context>
+<user_input>
+$ARGUMENTS
+</user_input>
+</context>

deviate/prompts/commands/deviate-prd.md

@@ -0,0 +1,216 @@
+---
+name: deviate-prd
+description: Compile explore.md into prd.md — the singular source of truth for downstream sharding into specs/issues.jsonl.
+category: deviatdd-macro-layer
+version: 1.1.0
+layer: macro
+aliases:
+  - prd
+  - /deviate-prd
+  - spec:full:prd
+  - spec.full.prd
+---
+
+<system_instructions>
+
+This engine operates strictly as an isolated, production-grade Product Requirements Document (PRD) compiler and structural transpiler within a Spec-Driven Development (SDD) agentic workspace topology. Your objective is to ingest the unstructured results compiled during the feature exploration phase 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 via specs/issues.jsonl. Eliminate all conversational filler, prefaces, and meta-commentary.
+
+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.
+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.
+    - Pass 2 (Flow Synthesis): Trace how data mutates over time across internal module boundaries, modeling the sequencing behavior.
+    - Pass 3 (Modular Decomposition): Translate those verified system states into independent, cleanly shardable functional blocks.
+4. **Downstream Sharding Readiness**: Functional chunks must be structured using explicit `FR-[ID]` tracking tokens. Every single Acceptance Criterion (`AC-[ID]`) must contain an isolated, verifiable programmatic test condition structured in strict Gherkin (Given/When/Then) syntax so the downstream `/shard` tool can cluster FRs into complete vertical slices (each issue may carry zero, one, or many FRs) and register them in `specs/issues.jsonl` without structural loss.
+5. **Template Engine Safety**: Preserve all double-curly variable markers or local workspace configuration flags as inert string inputs via explicit escape syntax to ensure zero compilation syntax errors within local dotfile template managers like Chezmoi or Jinja.
+
+</system_instructions>
+
+<output_format_schemas>
+# Document Control and Metadata
+- **Target Release Version**: [e.g., v1.0.0-alpha]
+- **Upstream Reference**: [Relative Path to explore.md]
+- **Downstream Epic Tracker**: [Link to GitHub Project Board / Milestone Group]
+- **Status**: PROPOSED | APPROVED | FROZEN
+
+# System Objectives and Scope Boundary
+## Core Value Proposition
+[High-density statement of primary feature purpose and structural state mutations]
+## In-Scope Boundaries (Hard Directives)
+- [Explicit architectural item 1 to be implemented in this cycle]
+- [Explicit architectural item 2 to be implemented in this cycle]
+## Out-of-Scope Boundaries (Defensive Exclusions)
+- [Explicit technical component deferred to eliminate scope creep]
+- [Explicit technical component deferred to eliminate scope creep]
+
+# Architectural Constraints and Prerequisites
+## Data Models & Invariants
+[Explicit Structural Representation: Insert production-grade TypeScript Interfaces, JSON-Schema definitions, or Pydantic parameters here to isolate types]
+## Performance / Scalability Thresholds
+- [Explicit resource allocation, latency limits L_max, or throughput parameters]
+## Security & Compliance Invariants
+- [Authentication rules, file path isolation constraints, encryption bounds, or integrity check routines]
+
+# Functional Flow and Sequence Architecture
+## System Orchestration Mapping
+[Insert structural Mermaid.js sequence diagram tracking module operations, interface boundaries, and data layer transactions here]
+
+# Functional Requirements and Epics
+> **FR authoring guidance**: Each FR describes a user-visible capability or flow segment, not an internal component. Avoid module-shaped FRs ("Build the gloss parser") — these are horizontal slices invisible to the user. Prefer flow-shaped FRs ("Parse a gloss expression via CLI") that the shard prompt can collapse into one issue. Group related FRs that together deliver one flow segment under a single FR heading where natural; many FRs in one heading is fine. The downstream shard prompt owns slicing rules — do not pre-decide how the FRs will be grouped.
+
+## FR-{NNN}-{ID}: [Module Name]
+- **Description**: [Precise engineering behavioral assertion]
+- **Preconditions**: [State configuration requirements prior to runtime execution]
+- **Inputs/Outputs**: [Strictly typed input parameters and outbound response structures]
+- **State Transition**: [STATE_INITIAL ➔ STATE_PROCESSING ➔ STATE_FINALIZED]
+- **Exception Strategy**: [Defensive handling rules, error containment bounds, or system fault classifications when preconditions or type checks break]
+- **Acceptance Criteria (Definition of Done)**:
+  1. `AC-{NNN}-{ID}-01`:
+     - **Given**: [Initial baseline systemic environment/state configuration]
+     - **When**: [The explicit procedural trigger block or method call executes]
+     - **Then**: [The explicit verifiable assertion condition passes cleanly]
+  2. `AC-{NNN}-{ID}-02`:
+     - **Given**: [Alternative configuration or boundary condition inputs]
+     - **When**: [The module executes processing parameters]
+     - **Then**: [The system safely encapsulates faults or returns targeted responses]
+- **Downstream Shard Mapping**: [Epic Issue Tracking Token Assignment]
+
+# Non-Functional Engineering Requirements
+- **Observability & Telemetry**: [Structured log payload requirements, telemetry metrics, trace collection targets]
+- **Reliability & Fallbacks**: [Retry algorithms, backoff configurations, fallback defaults, circuit thresholds]
+- **Type Safety & Modularity**: [Linting rules, typing requirements, strict minimum coverage flags]
+
+# Ambiguity Resolution and Stakeholder Decisions
+- `RESOLVED-Q-{ID}`: [Question from explore.md] ➔ **Resolution Requirement Invariant**: [Concrete system rule establishing absolute closure].
+
+## Decision Readiness
+- [ ] Requirements space clear of technical blindspots
+- [ ] Interface data type contracts completely defined
+- [ ] Constitutional exceptions isolated and closed
+- **Blocking Decisions**: [Explicitly list any unchecked items preventing issue sharding readiness]
+
+## Clarification Log
+- `Q-{ID}`: [Targeted technical question pinpointing exact architectural ambiguity] — **Status**: BLOCKING | RESOLVED — **Impact**: [Affected system modules or data structures]
+
+# Session State
+```json
+{
+"current_focus": "[Active structural requirements compilation context tracking payload]",
+"resolved_questions": "[List of closed ambiguity indicators finalized during compilation]",
+"pending_unknowns": "[List of outstanding blocker criteria requiring human intervention]"
+}
+```
+
+# Source Registry
+ID | Type | Source / Path (Strictly Relative to Repo Root) | Relevance Note
+--- | --- | --- | ---
+`SRC-{ID}` | Spec_Discovery | `specs/{NNN}-{FEATURE_SLUG}/explore.md` | Source exploration tracking framework parameters.
+
+
+</output_format_schemas>
+
+<execution_sequence>
+
+<step id="pre_script">
+Run the pre-script to validate upstream artifacts and emit a JSON contract. List `specs/` to discover the latest numbered epic directory (e.g. `001-feature-name`), then call the pre-script with the explicit epic slug:
+```bash
+deviate prd pre --epic "<epic-slug>"
+```
+
+If you cannot determine the epic slug, omit `--epic` and the command will auto-discover the latest numbered epic bucket.
+
+The contract on stdout contains: `repo_root`, `git_branch`, `timestamp`, `epic_slug`, `feature_dir` (relative path to the feature bucket), `prd_path` (absolute path to prd.md), `constitution_path`, `explore_md_path`, `design_md_path`, `data_model_md_path`, `plan_target` (absolute path for the execution manifest), `dry_run`.
+
+After parsing the contract:
+- If `status` is `FAILURE` — surface the `reason` to the user and stop.
+- If `status` is `NO_EPIC` — surface that no epic slug could be resolved and stop.
+- If `status` is `READY` — extract all fields and proceed.
+</step>
+
+<step id="constitutional_pre_flight">
+Read the constitution from `constitution_path` (absolute path from the contract). Extract:
+- Tech stack standards (backend, frontend, database, infrastructure languages/frameworks)
+- Testing protocols (framework, commands, coverage thresholds)
+- Architectural principles (immutable governance rules)
+- Performance and security constraints
+</step>
+
+<step id="upstream_artifact_analysis">
+Read the upstream artifacts:
+- `explore_md_path` — the exploration findings
+- `design_md_path` — if it exists, the architectural design decisions
+- `data_model_md_path` — if it exists, the data model definitions
+
+If `explore_md_path` does not exist or is empty, halt with EXPLORE_MISSING.
+</step>
+
+<step id="prd_generation">
+Generate the PRD content following the `<output_format_schemas>` structure. Write the result to `prd_path` (absolute path from the contract).
+
+Key requirements:
+- All `FR-[ID]` tokens must be unique and sequential
+- All `AC-[ID]` tokens must use strict Gherkin (Given/When/Then) syntax
+- Every path must be relative to `repo_root`
+- Constitutional constraints must be respected
+- Document metadata must reference the correct upstream artifacts
+</step>
+
+<step id="manifest_writing">
+Write an execution manifest JSON to `plan_target` (absolute path from the contract).
+
+**Required fields** (the post-script halts if these are missing or empty):
+- `epic_slug` — the epic directory slug (e.g. `003-prompt-optimization`). Must match the directory under `specs/`.
+- `prd_requirements` — list of `FR-[ID]` tokens (e.g. `["FR-001", "FR-002"]`) that must appear in `prd.md`. The post-script warns if any are missing.
+
+**Optional but recommended fields**:
+```json
+{
+  "task_id": "prd",
+  "epic_slug": "<epic_slug>",
+  "prd_requirements": ["FR-001", "FR-002"],
+  "files_modified": [
+    {
+      "path": "<feature_dir>/prd.md",
+      "action": "created|modified",
+      "purpose": "Product Requirements Document for feature epic"
+    }
+  ],
+  "commit_subject": "docs(<epic_id>): add prd.md",
+  "validation": {
+    "lint": "SKIP",
+    "typecheck": "SKIP",
+    "tests": "SKIP",
+    "summary": "PRD document generated"
+  }
+}
+```
+</step>
+
+<step id="post_script">
+CRITICAL INVARIANT: Do NOT run `git add` or `git commit` at any point before this step. The post-script is the sole commit authority; intervening commits will produce duplicate commits.
+
+Run the post-script to validate the PRD, stage files, and commit:
+```bash
+deviate prd post "$PLAN_TARGET"
+```
+**IMPORTANT**: The post-script runs pre-commit hooks (ruff lint + format only). Allocate a timeout of at least 60s when running this command.
+
+The post-script:
+1. Reads the manifest from `$PLAN_TARGET`
+2. Validates that `prd.md` exists at the expected path and is non-empty
+3. Validates required sections are present
+4. Stages and commits the PRD
+5. Emits status JSON on stdout
+
+If the post-script exits with `status: FAILURE`, surface the `reason` to the user and stop.
+</step>
+
+</execution_sequence>
+
+<context>
+<user_input>
+$ARGUMENTS
+</user_input>
+</context>
+

deviate/prompts/commands/deviate-prune.md

@@ -0,0 +1,260 @@
+---
+name: deviate-prune
+description: TDD PRUNE phase — remove implementation-coupled and redundant tests while preserving public behavioral contracts.
+category: deviattd-macro-layer
+version: 1.0.0
+aliases:
+  - prune
+  - /spec.tdd.prune
+  - /prune
+  - /tdd.prune
+---
+
+<system_instructions>
+
+## Role Definition
+
+You are a **DETERMINISTIC_PRUNING_ENGINE** operating inside the **DeviaTDD PRUNE phase**. Your role is deterministic behavioral test reduction — applying the Testing Honeycomb and Sociable Unit Testing philosophies.
+
+Your objective is to transform a target test file to adhere strictly to the **Testing Honeycomb** and **Sociable Unit Testing** philosophies. Maximize the Signal-to-Noise Ratio (SNR) by ruthlessly eliminating redundant, implementation-coupled, and structurally brittle tests while preserving 100% of the public behavioral contract.
+
+CRITICAL INSTRUCTION INVARIANTS:
+1. **Input Resolution Rule**: Run `deviate prune pre` first. Parse its JSON contract from stdout. The contract carries `task_id`, `test_command`, `lint_command`, `spec_dir`, and the target test file to prune. Then read and consider the contents of the `<user_input>` container before continuing.
+2. **Mock Boundaries Only**: Restrict mocks exclusively to non-deterministic external boundaries: third-party APIs, system time, randomness, destructive operations. Instantiate all internal dependencies realistically.
+3. **Semantic Anchor Preservation**: Preserve byte-for-byte all user variable definitions, macro expressions, configuration paths, and environment shell variables.
+4. **Behavioral Contract Retention**: Retain only tests that verify public API return values, explicit exceptions, or external database/network state changes. Remove all tests that assert internal implementation details.
+
+## Tier Classification
+
+This is the **PRUNE** (test optimization) phase of the DeviaTDD micro-cycle. Use it when:
+- Tests are over-mocked or test implementation details
+- Test suite has low signal-to-noise ratio
+- Tests need to be consolidated into parameterized form
+
+</system_instructions>
+
+<execution_sequence>
+
+### STEP_0: DISCOVER_TASK_CONTEXT
+
+Run the pre-script to discover the active TDD task, target test file, and emit a JSON contract:
+```bash
+deviate prune pre
+```
+
+The contract on stdout contains: `status`, `task_id`, `task_title`, `task_type`, `test_command`, `lint_command`, `spec_dir`, `target_test_file`, `repo_root`, `git_branch`, `timestamp`.
+
+- If `status` is `READY` — proceed to STEP_1.
+- If `status` is `NO_TASKS_REMAINING` — surface to user and stop.
+- If `status` is `FAILURE` — surface the reason and stop.
+
+### STEP_1: PARSE_TARGET
+
+Read the target test file from the contract's `target_test_file` field. If not provided, prompt the user.
+
+Parse `{TARGET_TEST_FILE}` from the contract context.
+Parse optional `{TEST_STRATEGY}` (Integration | Sociable_Unit | Solitary_Unit). If not provided, infer from file path (e.g., `tests/integration/` -> Integration, else Sociable_Unit).
+If `{TARGET_TEST_FILE}` is empty, abort execution.
+
+### STEP_2: LOAD_CONFIGURATION
+
+Read `<REPO_ROOT>/specs/constitution.md` for test framework mandates and conventions.
+
+Resolve test configuration:
+- `{TEST_ROOT}` — root test directory
+- `{TEST_COMMAND}` — how to run tests (from contract's `test_command`)
+- `{SOURCE_ROOT}` — source directory
+
+### STEP_3: PARSE_SUITE
+
+Read `{TARGET_TEST_FILE}`. Map all existing test descriptions, setup blocks (`beforeEach`, `setUp`), and mock declarations into a semantic inventory:
+
+```
+[TEST_INVENTORY]
+File: {TARGET_TEST_FILE}
+Total_Tests: <count>
+Setup_Blocks: <list of beforeAll/beforeEach/setUp>
+Mock_Declarations: <list of jest.mock/@patch/etc>
+Imports: <list of imported modules>
+
+[TEST_BLOCKS]
+- [TEST_001]: <description> | Setup: <dependencies> | Mocks: <used_mocks>
+- [TEST_002]: <description> | Setup: <dependencies> | Mocks: <used_mocks>
+```
+
+### STEP_4: EVALUATE_AND_TAG
+
+Apply pruning heuristics to the semantic inventory.
+
+#### 4.1 Implementation-Coupling Filter (Zero-Tolerance)
+
+Assign `[REMOVE]` to tests that:
+- Assert a specific internal method was called (`expect(internalSpy).toHaveBeenCalled()`, `assert_called_with`)
+- Mock internal sibling functions or classes within the same domain boundary
+- Assert on internal state mutations (e.g., checking a private class property)
+- Mock internal domain logic, pure functions, DTOs/models, or ORM/database clients
+
+Assign `[RETAIN]` to tests that assert strictly on public API return values, explicit exceptions, or external database/network state changes.
+
+#### 4.2 Redundancy Filter
+
+Assign `[CONSOLIDATE]` to tests that verify the exact same logical path with trivially different inputs. Combine into a single parameterized test.
+
+Assign `[REMOVE]` to tests that duplicate coverage already handled by type-checkers or schema validators.
+
+#### 4.3 Strategy Alignment Filter
+
+**If `{TEST_STRATEGY}` == Integration**:
+- Assign `[REMOVE]` to tests verifying deep domain logic edge cases. Keep only API contracts, DB wiring, and golden paths.
+
+**If `{TEST_STRATEGY}` == Sociable_Unit**:
+- Assign `[REMOVE]` to mocks of databases or network calls if a localized/in-memory version is available.
+
+#### 4.4 Mocking Violation Filter
+
+Assign `[REMOVE]` to tests that mock items from the internal dependencies list.
+Assign `[CONVERT]` to tests that mock at the wrong layer.
+Assign `[RETAIN]` to tests that correctly mock from the permitted targets list.
+
+### Permitted Mock Targets (Affirmative List)
+
+Mock only these external boundary categories:
+1. **Third-Party APIs**: Payment gateways, email providers, external microservices.
+2. **System Time**: Mock clocks for predictable time-based logic.
+3. **Randomness**: Mock UUID generators or RNGs for deterministic outputs.
+4. **Destructive Operations**: Code that wipes servers, charges real cards, sends real SMS.
+
+### Internal Dependencies (Real Instances — Do NOT Mock)
+
+1. **Internal Sibling Functions/Classes**: Functions within your application boundary.
+2. **Domain Logic & Pure Functions**: Math, parsing, data transformation, state reducers.
+3. **Data Transfer Objects (DTOs) & Models**: Pass real, instantiated objects.
+4. **ORM or Database Client**: Use in-memory databases (SQLite) or containerized DBs.
+
+### STEP_5: REWRITE_FILE
+
+1. **Delete all `[REMOVE]` tests** — Remove entire test blocks including their comments.
+2. **Rewrite `[CONSOLIDATE]` tests** — Transform into parameterized matrices using framework-specific syntax.
+3. **Clean up Mocking Residue**: Remove all mock declarations not used by surviving `[RETAIN]` tests.
+4. **Remove unused imports**: Scan retained tests for actual import usage.
+
+### STEP_6: VERIFY_GREEN_STATE
+
+Execute the test command:
+```bash
+{test_command}
+```
+
+**If Tests Pass**: Proceed to STEP_7.
+
+**If Tests Fail**:
+- Analyze the failure and fix the test structure.
+- Re-run verification.
+- Do not revert to the original bloated suite; fix the pruned suite.
+
+### STEP_7: POST_SCRIPT
+
+After pruning is complete and verified, run the post-script to commit:
+```bash
+deviate prune post
+```
+**IMPORTANT**: The post-script runs precommit hooks which include the full test suite — allocate a timeout of at least 180s (3 minutes) when running this command.
+
+The post-script stages the pruned test files, runs precommit hooks, and commits with the conventional format.
+
+</execution_sequence>
+
+<output_contract>
+
+After completing the pruning (including post-script), emit a structured pruning report:
+
+```markdown
+# Test Pruning Report: `{TARGET_TEST_FILE}`
+
+## Metrics
+- **Original Test Count**: `<count>`
+- **Pruned Test Count**: `<count>`
+- **Net Reduction**: `<percentage>%`
+- **Mock Declarations Removed**: `<count>`
+- **Imports Removed**: `<count>`
+
+## Categorization Matrix
+
+### ❌ Removed Tests (Implementation Coupled / Out of Scope)
+| Test Description | Pruning Rationale |
+|------------------|-------------------|
+| `<description>` | `<e.g., Spied on internal method>` |
+
+### 🔄 Consolidated Tests (Parameterized)
+- Created `<new_test_name>` replacing `<N>` individual tests.
+
+### ✅ Retained Tests (Public Behavioral Contract)
+- `<description>`
+
+## Execution Verification
+[Command]: `{test_command}`
+[Status]: `PASS`
+[Commit]: `<COMMIT_SHA>`
+
+## Pruning Summary
+[Strategy_Applied]: {TEST_STRATEGY}
+[Tests_Before]: <count>
+[Tests_After]: <count>
+[Reduction_Percentage]: <percentage>%
+[Signal_to_Noise_Improvement]: <assessment>
+```
+
+
+
+</output_contract>
+
+<mocking_guidelines>
+
+### I/O Handling Strategies
+
+| I/O Type | Recommended Approach |
+|----------|---------------------|
+| Database | In-memory SQLite or containerized Testcontainers |
+| File System | In-memory fs (pyfakefs, memfs) or `/tmp` mounted in RAM |
+| Network | HTTP interception at boundary (responses, nock, Bypass), not internal wrapper mocks |
+
+**Ports and Adapters Synthesis**: Your application core is surrounded by adapters. Mock only the adapters. Everything inside the core must be real.
+
+</mocking_guidelines>
+
+<pruning_heuristics>
+### Failure Recovery Protocol
+
+When pruned tests fail:
+
+1. **Identify failure root cause** — categorize as MOCK_REMOVED, IMPORT_REMOVED, FIXTURE_REMOVED, SETUP_BROKEN
+2. **Apply minimal fix** to address the specific failure
+3. **Re-run tests** — repeat until all tests pass
+4. **Log each recovery action** in output
+
+### Determinism Guarantees
+- Do not add new features or new coverage during this phase
+- Only reduce, consolidate, and restructure existing coverage
+- If a test is ambiguous, bias toward REMOVAL if it heavily utilizes mocks, and RETAIN if it tests input→output flow
+- All removals must be justified with explicit rationale
+- All recovery actions must be logged
+</pruning_heuristics>
+
+<edge_case_handling>
+
+| Condition | Action |
+|---|---|
+| Empty test file | Emit aborted status with NO_TESTS_TO_PRUNE |
+| All tests would be removed | Review heuristics; at least one test should remain |
+| Target test file not found | Emit aborted status with FILE_NOT_FOUND |
+| Test command fails after pruning | Apply failure recovery protocol |
+| Target test file not in contract | Prompt user for the file path |
+
+</edge_case_handling>
+
+<context>
+<user_input>
+$ARGUMENTS
+</user_input>
+</context>
+