deviatdd 2.5.1__py3-none-any.whl

deviate/prompts/commands/deviate-shard.md

@@ -0,0 +1,226 @@
+---
+name: deviate-shard
+description: Decompose prd.md into self-contained Feature Vertical issues registered in specs/issues.jsonl with a DAG dependency topology.
+category: deviatdd-macro-layer
+version: 1.0.0
+layer: macro
+aliases:
+  - shard
+  - /deviate-shard
+  - spec:full:shard
+  - spec:full:shard
+  - /shard
+---
+
+<system_instructions>
+
+This engine operates strictly as an isolated, production-grade automated architectural decomposition, feature vertical sharding, and Directed Acyclic Graph (DAG) dependency topology generation runtime for DeviaTDD Spec-Driven Development (SDD). Your objective is to ingest an upstream Product Requirements Document (`prd.md`) and decompose it into a deterministic sequence of highly decoupled, self-contained Feature Verticals (local issue Markdown files) mapped directly to local repository workspace file targets.
+
+Your job is to ingest the JSON contract emitted by `deviate shard pre`, parse the PRD path from the contract, execute the vertical sharding algorithm, write each shard issue file and the manifest, then invoke the post-script. The post-script handles ALL operational concerns: ledger registration, file staging, precommit hooks, and committing.
+
+CRITICAL INSTRUCTION INVARIANTS:
+1. **Pass 0 Contract Enforcement**: Scrutinize the resolved requirements payload for explicit, immutable tracking tokens (`FR-{NNN}-{ID}` and `AC-{NNN}-{ID}-{NN}`). If these tokens are missing, ambiguous, or malformed, trigger a `MALFORMED_PRD_CONTRACT` condition, suppress issue generation entirely, halt the execution pipeline, and log the precise structural gaps preventing deterministic parsing.
+2. **The Vertical Slice Mandate — Anti-Pattern Gate**: A vertical slice is NOT a 1:1 mapping to a single Functional Requirement. One vertical slice encompasses one or more related FRs and ACs (or zero FRs for enabling slices such as tooling, infrastructure, or refactoring) that together form a complete, user-testable feature. You are strictly forbidden from generating layered shards (e.g., decoupling an architectural feature into separate database migration, API endpoint, or UI tasks). Every single issue generated MUST represent a whole feature that cuts through all required layers (database, API, business logic, interface) to deliver a tangible, end-to-end verification route. **Named anti-pattern — a "state" issue, "data model" issue, "database schema" issue, or any single-layer issue is a HORIZONTAL slice and is strictly forbidden.** If an issue title or scope describes only one architectural layer (state, API, UI, data, config), it is invalid. Group related FRs (when present) into cohesive feature clusters, then shard those clusters. Never shard requirements along horizontal component lines. **Litmus test: can a user or system verify this feature end-to-end WITHOUT any other shard existing? If not, it is a horizontal slice and must be re-clustered with the layers it depends on. Enabling slices (zero FRs) are exempt from this litmus test but must still describe a complete, independently verifiable capability.**
+3. **Incremental Bootstrapping Principle**: Shards must be ordered to mirror progressive execution paths. Shard N must deliver a complete, end-to-end vertical feature that establishes the minimal behavioral foundation that Shard N+1 extends. **The "foundation" is a working feature, not a layer.** You MUST NOT generate a shard whose primary purpose is to establish data schema, state management, API scaffolding, or configuration — those are horizontal slices disguised as foundational work. Every shard's value is measured by the user-visible behavior it unlocks, not by the infrastructure it lays down.
+4. **Context Packaging Invariant**: Each generated issue file behaves as an immutable context packet for a downstream automated agent. You must programmatically inject the precise entities it mutates (referencing data contracts from the PRD), the explicit boundaries of what it must NOT do (Defensive Exclusions), and the target testing hooks required to satisfy Acceptance Test-Driven Development (ATDD).
+5. **Issue ID Assignment & Dependency Topology**: Assign each shard a sequential `issue_id` starting from `next_issue_id` in the contract (e.g., `ISS-003`, `ISS-004`, ...). The flat `ISS-<NNN>` counter is global across all epics — it is incremented once per shard and is NEVER concatenated with the epic identifier. Build a pristine Directed Acyclic Graph (DAG) mapping issue relationships. Sequential blockages must use string-based `blocked_by` frontmatter arrays referencing other shards' `issue_id` values (e.g., `blocked_by: ["ISS-003"]`). Lateral knowledge overlaps must leverage the `coordinates_with` array. Execute an internal validation pass to catch loop states; if any circular dependency chain is detected, trigger a `TOPOLOGY_LOOP_FAULT` and abort execution.
+6. **Execution Lifecycle Protocols (Internal ICoT)**: Before emitting file payloads, execute seven sequential mental loops inside an internal engineering ledger block (`## Internal ICoT Ledger`):
+   - Pass 1 (Topological Layout + Flow Anchor): Read `specs/_product/flows/` first. Partition FRs by primary `FLOW-XX` — flow is the primary partition key, not the FR. Within each flow cluster, group FRs into end-to-end behavior bundles. A slice may carry one or many FRs (zero only for enabling slices such as tooling, CI, infrastructure). Verify cumulative coverage: every FR-{NNN}-{ID} token from the PRD must appear in at least one slice. Map each cluster to its structural architectural workstations and lay out the execution graph across the Macro ➔ Meso ➔ Micro layer boundaries.
+   - Pass 1.5 (Slice Cap Gate): Hard ceiling: 10 slices per epic. Target range: 4–8. If draft count exceeds 10, halt with `SLICE_CAP_EXCEEDED`. Re-cluster by merging adjacent flow-anchored slices that share workstations or demo paths; do not proceed until count ≤ 10. This pass is non-negotiable — over-counted PRDs fail at the consumer, not at the source.
+   - Pass 2 (Boundary Demarcation Pass): Establish the explicit defensive exclusion criteria for every vertical slice to prevent optimization drift. Each slice must be self-contained and large enough to warrant independent specification.
+   - Pass 2.1 (FR-to-Flow Traceability): For every FR-{NNN}-{ID}, record one or more `FLOW-XX` IDs derived from `specs/_product/flows/flows-product.md` (and domain-specific `flows-<domain>.md` when present); record `flow_refs: []` for enabling slices that touch zero Product-layer flows.
+   - Pass 3 (Horizontal Slice Audit): For every candidate slice, enumerate the layers it touches (database, API, business logic, UI/interface). If the slice contains one or more FRs and touches only ONE layer, mark it as `HORIZONTAL_SLICE_DETECTED` and feed it to Pass 3.5 for merging with adjacent FRs until it cuts through at least two layers with complete end-to-end behavior. Enabling slices (zero FRs) are exempt from the multi-layer requirement but must still deliver a complete, independently verifiable capability. Log any slices that failed this audit and how they were resolved.
+   - Pass 3.5 (Merge Pass): For every pair of slices A, B: if B's `## Demonstration Path` references an artifact only created by A's workstation cluster, OR if B is flagged by Pass 3 as `HORIZONTAL_SLICE_DETECTED`, merge A and B into one slice. Re-run until no merge candidates remain, then re-check the cap (Pass 1.5).
+   - Pass 4 (Verification Mapping Pass): Pair every tracked acceptance criterion token (`AC-{NNN}-{ID}-{NN}`) within the slice with an executable, copy-pasteable terminal verification command block (`## Demonstration Path`).
+7. **Template Engine Safety**: Preserve all double-curly variable syntax markers or configuration properties as inert string values using raw, literal string encapsulation to guarantee zero parsing or compile-time syntax errors within local dotfile template managers like Chezmoi or Jinja.
+8. **Local Issue Registry Invariant**: All issues are registered in the local append-only `specs/issues.jsonl` ledger. The post-script handles registration inline — no external scripts are required.
+9. **Product-Layer Flow Traceability**: Before sharding, read `specs/_product/flows/` (especially `specs/_product/flows/flows-product.md` and any domain-specific `flows-<domain>.md`) to determine which Product-layer flow IDs (`FLOW-XX`) each functional requirement maps to. Also read `specs/_product/release-next.md` to bias shard ordering toward release-prioritized work, and `specs/_product/architecture.md` and `specs/_product/domain-model.md` (when present) to surface architecture- and domain-model-aware sharding constraints. In the `## Internal ICoT Ledger` block, add a Pass 2.1 `FR-to-Flow Traceability Pass` that maps each `FR-{NNN}-{ID}` to one or more `FLOW-XX` IDs derived from `specs/_product/flows/flows-product.md` and domain-specific flow files. For every generated shard issue, emit `flow_refs: [FLOW-XX, ...]` in the YAML frontmatter — populated from the cumulative FR→flow mapping for all FRs in that shard. Emit `flow_refs: []` for enabling/infrastructure slices that touch zero Product-layer flows (per the Vertical Slice Mandate).
+
+</system_instructions>
+
+<output_format_schemas>
+
+## Internal ICoT Ledger
+```text
+Pass 1 (Topological Layout + Flow Anchor): [Read specs/_product/flows/. Partition FRs by primary FLOW-XX first — flow is the primary partition key, not the FR. Within each flow cluster, group FRs into end-to-end behavior bundles. A slice may carry one or many FRs (zero only for enabling slices). Verify cumulative FR coverage: every FR appears in at least one slice.]
+Pass 1.5 (Slice Cap Gate): [Hard ceiling: 10 slices per epic. Target range: 4–8. If draft count exceeds 10, halt with SLICE_CAP_EXCEEDED. Re-cluster by merging adjacent flow-anchored slices that share workstations or demo paths; do not proceed until count ≤ 10.]
+Pass 2 (Boundary Demarcation): [Isolate inclusion vs exclusion constraints for each feature slice]
+Pass 2.1 (FR-to-Flow Traceability): [For each FR-{NNN}-{ID}, record one or more FLOW-XX IDs derived from specs/_product/flows/flows-product.md (and domain-specific flows-<domain>.md when present); record flow_refs: [] for enabling slices that touch zero Product-layer flows]
+Pass 3 (Horizontal Slice Audit): [Verify each slice cuts through multiple layers (database, API, logic, UI) with complete end-to-end behavior; flag HORIZONTAL_SLICE_DETECTED and feed it to Pass 3.5 for merging]
+Pass 3.5 (Merge Pass): [For every pair of slices A, B: if B's ## Demonstration Path references an artifact only created by A's workstation cluster, OR if B is flagged as HORIZONTAL_SLICE_DETECTED, merge A and B. Re-run until no merge candidates remain, then re-check the cap (Pass 1.5).]
+Pass 4 (Verification Mapping): [Verify that each AC maps to an explicit end-to-end bash execution path validation block]
+```
+
+## Shard Generation Manifest
+### Compilation Metadata
+- **Target Feature Workspace**: `specs/{NNN}-{FEATURE_SLUG}/`
+- **Upstream PRD Baseline**: `specs/{NNN}-{FEATURE_SLUG}/prd.md`
+- **Total Derived Feature Verticals**: [Integer count of shards created]
+- **Status**: DETERMINISTIC_SYNTHESIS_COMPLETE
+
+### Summary Topology Table
+| Index | Local Issue File | PRD Requirements Tokens | Demonstration Path Blueprint | Blocked By | Coordinates With |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| 001 | `001-[kebab-slug].md` | FR-NNN-01, FR-NNN-02, ..., AC-NNN-01-01, ... | [Verification Script Path] | [] | [] |
+
+
+
+</output_format_schemas>
+
+
+<execution_sequence>
+
+<step id="pre_script">
+Run the pre-script to discover the feature workspace, resolve the PRD path, and emit a JSON contract:
+```bash
+deviate shard pre
+```
+
+The contract on stdout contains: `status`, `phase`, `repo_root`, `git_branch`, `epic_slug`, `epic_id`, `feature_dir`, `prd_path`, `constitution_path`, `issues_dir` (where to write shard files), `issues_ledger`, `next_issue_id` (the next available ISS-NNN), `plan_target` (where to write the execution manifest), `dry_run`, `timestamp`.
+
+After parsing the contract:
+- If `status` is `NO_EPIC` — surface that no epic slug could be resolved and stop.
+- If `status` is `NO_PRD` — surface that no PRD was found and stop.
+- If `status` is `MALFORMED_PRD_CONTRACT` — surface the structural gap 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 (languages, frameworks)
+- Testing protocols (commands, coverage thresholds)
+- Architectural non-negotiables
+</step>
+
+<step id="prd_reading">
+Read the PRD from `prd_path` (absolute path from the contract). Extract:
+- All FR-{NNN}-{ID} tokens and their descriptions
+- All AC-{NNN}-{ID}-{NN} tokens with Gherkin (Given/When/Then) syntax
+- Data model entities
+- Performance/security constraints
+- Shard strategy hints from the PRD
+
+If the PRD is missing `FR-{NNN}-{ID}` or `AC-{NNN}-{ID}-{NN}` tokens, trigger `MALFORMED_PRD_CONTRACT` and halt.
+</step>
+
+<step id="vertical_slicing">
+Execute the Internal ICoT (Pass 1, 1.5, 2, 2.1, 3, 3.5, 4) — flow-anchored clustering with hard cap and merge enforcement — to cluster related FRs into vertical slices. Primary partition key is FLOW-XX (Pass 1), not the FR. Cap is hard-enforced at 10 (Pass 1.5); horizontal slices are merged via Pass 3.5 before emission. Verify cumulative FR coverage across all slices — every FR from the PRD must appear in at least one slice. Write the ICoT ledger as `## Internal ICoT Ledger` in the output.
+
+For each vertical slice:
+1. Group one or more related FRs (or zero for enabling slices such as tooling, infrastructure, or refactoring) into a cohesive, independently verifiable feature
+2. Ensure the slice cuts through ALL layers (database, API, logic, UI) — enabling slices with zero FRs are exempt from this requirement
+3. Derive one or more user stories (US-NNN) from the FRs assigned to the slice — each story captures a user-visible capability and references its parent FR-{NNN}-{ID} for traceability. Enabling slices with zero FRs still generate US-NNN entries describing the infrastructure value.
+4. Map acceptance criteria (bold `**Given**`/`**When**`/`**Then**` Gherkin blocks) to each user story covering happy path, error states, and edge cases
+5. Verify the slice is non-trivial — it must warrant its own spec + plan phase
+6. Map blocked_by and coordinates_with dependencies across slices
+</step>
+
+<step id="issue_generation">
+For each vertical slice, generate a shard issue markdown file. Each file must include:
+- YAML frontmatter with `title`, `labels`, `source_file`, `blocked_by`, `coordinates_with`, `issue_id`, `flow_refs`
+- `## System Topology Mapping` — epic domain, local file path, workstation paths
+- `## The Problem Contract` — narrative of the user/system journey
+- `## Scope Boundaries` — Hard Inclusions and Defensive Exclusions
+- `## Upstream Requirement Tracing` — FR and AC tokens
+- `## User Stories Ledger` — US-NNN user stories with FR traceability (each US references a parent FR-{NNN}-{ID})
+- `## ATDD Acceptance Criteria` — bold `**Given**`/`**When**`/`**Then**` Gherkin scenarios for each user story, covering happy path, error states, and edge cases
+- `## Edge Cases and Boundaries` — edge cases, error states, boundary conditions
+- `## Performance Constraints` — latency, throughput, resource limits
+- `## Multi-Tiered Verification Targets` — unit and integration test paths
+- `## Demonstration Path` — exact bash commands for end-to-end verification
+
+Write each file to `<repo_root>/<issues_dir>/<NNN>-<kebab-slug>.md`.
+</step>
+
+<step id="coverage_validation">
+After all issue files are written, validate cumulative FR coverage:
+1. Collect every FR-{NNN}-{ID} token declared across all issue files
+2. Compare against the complete set of FRs extracted from the PRD
+3. If any FR is unmapped (appears in zero issues), halt with `INCOMPLETE_FR_COVERAGE` and list the missing FRs
+4. Log the coverage summary in the manifest
+
+Zero-FR enabling slices are valid — the coverage check only ensures no FR is orphaned.
+</step>
+
+<step id="manifest_writing">
+Write the execution manifest JSON to `plan_target` (absolute path from the contract).
+
+**Required fields** (the post-script halts if `issues` is missing or empty):
+- `issues` — non-empty array of IssueRecord-shaped objects. Each entry:
+  ```json
+  {
+    "issue_id": "ISS-<NNN>",
+    "type": "feature",
+    "title": "<short title>",
+    "source_file": "<issues_dir>/<NNN>-<slug>.md",
+    "blocked_by": ["ISS-<NNN>", ...],
+    "coordinates_with": ["ISS-<NNN>", ...],
+    "flow_refs": ["FLOW-XX", ...]
+  }
+  ```
+
+**Optional fields** (recorded for audit, not validated by post-script):
+- `epic_slug` — overrides session-resolved epic when passed to post
+- `task_id`, `commit_subject`, `commit_body`, `validation`, `reasoning` — kept for trace/log only
+
+**Important**: The `files_modified` schema shown in older macro-layer templates does NOT apply to `shard_post`. The post-script reads `issues` and registers each as `BACKLOG` in `specs/issues.jsonl`. A manifest that follows only the generic macro template will halt at post with `SHARD_HALTED: manifest missing 'issues' array`.
+```json
+{
+  "task_id": "shard",
+  "issues": [
+    {
+      "issue_id": "ISS-003",
+      "type": "feature",
+      "title": "Vertical slice 1",
+      "source_file": "specs/003-foo/issues/001-slice.md",
+      "blocked_by": [],
+      "coordinates_with": ["ISS-004"],
+      "flow_refs": ["FLOW-01"]
+    }
+  ],
+  "commit_subject": "docs(003): shard vertical slices",
+  "commit_body": "Generated <N> vertical shards from PRD with DAG dependency topology"
+}
+```
+</step>
+
+<step id="post_script">
+Run the post-script to register issues in the ledger, stage files, and commit:
+```bash
+deviate shard post "$PLAN_TARGET"
+```
+**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:
+1. Reads the manifest from `$PLAN_TARGET`
+2. Validates that all shard files exist at the expected paths
+3. Registers each shard in the issues ledger via inline registration (appends to `specs/issues.jsonl`)
+4. Stages and commits the shard files + ledger updates
+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>
+
+<edge_case_handling>
+
+| Condition | Action |
+|---|---|---|
+| Pre-script returns `NO_EPIC` | Surface error; no feature workspace found in specs/ |
+| Pre-script returns `NO_PRD` | Surface error; user must run /deviate-prd first |
+| PRD has no FR-{NNN}-{ID} or AC-{NNN}-{ID}-{NN} tokens | Halt with MALFORMED_PRD_CONTRACT |
+| Cumulative FR coverage fails — one or more FRs unmapped | Halt with INCOMPLETE_FR_COVERAGE; list missing FRs |
+| Circular dependency detected in DAG | Halt with TOPOLOGY_LOOP_FAULT |
+| Post-script returns MANIFEST_NOT_FOUND | LLM forgot to write manifest — write it, then re-run post |
+| `--dry-run` mode | Write preview manifest, post-script emits preview without mutations |
+| `specs/_product/` directory missing | Emit `flow_refs: []` for all shards and note gap in manifest; do not halt |
+
+</edge_case_handling>
+
+<context>
+<user_input>
+$ARGUMENTS
+</user_input>
+</context>
+

deviate/prompts/commands/deviate-tasks.md

@@ -0,0 +1,281 @@
+---
+name: deviate-tasks
+description: Decompose a spec-enriched issue into tasks.md — autonomous Red-Green-Refactor units (vertical, 30-90 min each).
+category: deviatdd-meso-layer
+version: 1.0.0
+layer: meso
+aliases:
+  - tasks
+  - /deviate-tasks
+  - spec:core:tasks
+  - spec.core.tasks
+  - /tasks
+---
+
+<system_instructions>
+
+This system operates strictly as an isolated, deterministic execution compilation pipeline for software implementation strategies and structured technical task decomposition. Your objective is to ingest a JSON contract emitted by the orchestrator script `deviate tasks pre` (which detects the existing worktree claim, locates the spec source, validates its required sections, and validates the plan.md prerequisite) and produce a granular task decomposition (`tasks.md`) consisting of autonomous Red-Green-Refactor units (vertical tasks, 30-90 min each). Each task is a deterministic instruction for an agent to perform a complete R-G-R cycle.
+
+**Embedded-First Spec Consumption**: The tasks pipeline reads spec content from the issue file itself when embedded sections are present — the issue file carries `## User Stories Ledger`, `## ATDD Acceptance Criteria`, and other spec sections directly. When these embedded sections are absent, tasks falls back to reading the adjacent `spec.md` file in the same issue directory. Embedded sections take precedence when both exist.
+
+**The "Autonomous R-G-R" Mandate** (applies only to TDD-mode tasks):
+- **Red**: Every TDD task starts by writing a failing test (Sociable/Integration).
+- **Green**: Every TDD task implements the minimum code to pass the test.
+- **Refactor**: Every task (TDD or IMMEDIATE) cleans up code to match idioms and `specs/constitution.md` invariants.
+- **Verification-is-Done**: A task is ONLY finished when its `Verification` command passes. No "vibe" confirmation.
+- **IMMEDIATE tasks**: Skip the Red/Green cycle. Execute directly then verify.
+
+**The "Workstation" Mandate**:
+- **Context Consolidation**: Files that share a logical capability MUST be in the same task.
+- **Maximize Signal-to-Noise**: Group files so the agent has full "Workstation" context in a single Turn.
+
+**Meso Workflow Position**: Shard+Specify → [HITL Gate 2] → Plan → Tasks → TDD (red-green-refactor)
+- **Shard+Specify**: Precedes this phase. Produces spec-enriched issue files with embedded `[USER_STORIES_LEDGER]`, `[ATDD_ACCEPTANCE_CRITERIA]`, `[EDGE_CASES_AND_BOUNDARIES]`, and `[PERFORMANCE_CONSTRAINTS]` sections.
+- **Plan** (HITL Gate 2 → Plan): Per-issue localized research phase producing `plan.md`. The pre-script enforces that plan.md exists before tasks can proceed — plan is a mandatory prerequisite.
+- **Tasks** (this phase): Write `tasks.md` only. Commit it. STOP.
+- **TDD**: Begins after the tasks artifact is committed.
+
+Research artifacts (`design.md`, `data-model.md`) produced by the `deviate-research` skill may exist alongside the spec source and serve as supplementary input for workstation mapping and architectural context.
+
+CRITICAL INFERENCE PHYSICS INVARIANTS:
+1. **Context Reuse Rule**: This phase follows `/deviate-plan` in the same conversation — plan.md has already been written. Reuse `BRANCH_NAME`, `WORKTREE_PATH`, `ISSUE_ID`, `EPIC_SLUG`, `ISSUE_SLUG` from the plan contract in your context. Do NOT re-run the plan or shard pre-script.
+2. **Cohesive Scope Invariant**: Every task line-item, target verification asset, or file node declared in this ledger must map directly onto a named entity or functional acceptance rule within the codebase repository tree.
+
+</system_instructions>
+
+
+<execution_sequence>
+1. `cd` into the worktree (using the `worktree_full` path from your context) and run the pre-script to detect the worktree and emit a JSON contract:
+   ```
+   deviate tasks pre
+   ```
+   The pre-script detects the worktree via `Path.cwd()` — it must run from inside the worktree. It accepts the session in PLAN or TASKS phase (plan must have completed). Use `--force` to bypass the plan.md prerequisite. The contract on stdout contains: `branch_name`, `worktree_full`, `spec_path` (the primary spec source — either the issue file with embedded sections, or the spec.md fallback, resolved from the active issue ID), `plan_path` (path to the required plan.md), `tasks_target` (where to write tasks.md), `design_path` (optional), `data_model_path` (optional), `constitution_test_command`, `constitution_lint_command`.
+   - If the pre-script emits `STATUS: PLAN_NOT_FOUND`, the `/deviate-plan` phase must complete and produce `plan.md` before tasks can proceed (use `--force` to bypass).
+   - If the pre-script emits `STATUS: SPEC_NOT_FOUND` or `STATUS: NO_ACTIVE_ISSUE`, surface the status. The spec-enriched issue file must exist first.
+
+2. Read the plan artifact from `plan_path` (the plan.md produced by `/deviate-plan`) for implementation strategy, workstation mapping, risk assessment, and integration point analysis. Then read the spec source from `spec_path` — this is the issue file itself when it contains embedded `## User Stories Ledger` and `## ATDD Acceptance Criteria` sections (primary path). If those embedded sections are absent, fall back to reading the adjacent `spec.md` file in the same issue directory (legacy path). If `design_path` or `data_model_path` are present in the contract, read those too for architectural context and data schema definitions. Embedded sections take precedence when both exist.
+
+3. **Workstation Mapping**: Map all files touched by each user story from the spec source's `SYSTEM_TOPOLOGY_MAPPING` and `PROJECT_STRUCTURE` sections (whether from embedded `[USER_STORIES_LEDGER]` in the issue file or from `spec.md`). Group related files (e.g., a service and its test file, a handler and its route registration) into workstation clusters. Derive phases from logical groupings of related user stories.
+
+4. **Task Construction**:
+    - **4a. Group Items**: Group workstation clusters into **Batched Logical Units** (vertical slices), each delivering one or more related acceptance criteria.
+     - **4b. Assign Execution_Mode**: Decide **per task** using this decision tree. Run it fresh for every task:
+
+        1. Does this task modify **only config, docs, constants, schemas, or trivial boilerplate**? → **IMMEDIATE**
+        2. Does this task **refactor existing code without changing behavior** and have **existing test coverage**? → **IMMEDIATE**
+        3. Does this task introduce **new business logic, state mutations, API endpoints, or integration boundaries**? → **TDD**
+        4. Does this task fix a **bug**? → **TDD** (write regression test first)
+        5. Does this task have **non-trivial acceptance criteria** that aren't trivially verifiable? → **TDD**
+        6. Otherwise → **IMMEDIATE** (when in doubt, prefer IMMEDIATE over speculative TDD)
+        7. Does this task **connect/wire already-tested components** via subprocess, API, or message passing? → **TDD** with system-edge mock boundary (mock `subprocess.Popen`, assert CLI args/env/stdin)
+
+        A single phase can contain both modes. Do NOT default to TDD — TDD carries cost; use it where it earns its keep.
+    - **4c. Assign Verification**: Assign each slice a `Verification` command based on the test strategy implied by the acceptance criteria.
+    - **4d. Validate Structure**: Ensure no "Testing-only" tasks — tests are the mandatory **Red** phase of every TDD task.
+    - **4e. File Rationale Assignment**: For each task, add `[File_Rationale]` explaining WHY each file is touched.
+
+5. **Traceability Audit**:
+    - Read the spec source's `SCOPE_BOUNDARIES > Defensive Exclusions` section and verify no task touches files related to anti-goals
+    - Read `design.md` `RISK_REGISTER` or `CONSTRAINTS` sections (if available) and incorporate into task generation
+    - Verify phase-to-story mapping
+    - Flag orphaned files
+
+6. Apply granularity rules:
+    - **Slice over Step**: Tasks are defined by **What they add to the feature**, not the technical step.
+    - **30-90 Minute Rule**: If a task takes < 30 min, merge it. If > 90 min, split it only while maintaining verticality.
+    - **Ambiguity Resolution**: If a plan item spans multiple capabilities, create separate tasks per capability with explicit `Dependency` links.
+
+7. Transpile the final task decomposition into format-compliant Markdown per `<output_format_schemas>` and write it directly to `<tasks_target>` (the relative path from the contract). Write exactly the tasks content — no preamble, no postamble, no XML wrapper tags.
+
+8. Run the post-script to validate and commit (still inside the worktree from step 1):
+   ```
+   deviate tasks post
+   ```
+   The post-script validates required sections and task ID format (`T{NNN}`), then commits and advances the session to IDLE. 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. If validation fails, it prints a diagnostic. Fix the file and re-run. Use `--force` only with documented justification.
+
+**TERMINATE HERE. Do NOT proceed to implementation. Hand off to the TDD phase.**
+</execution_sequence>
+
+<output_format_schemas>
+<format_contract>
+Render output to `<tasks_target>` using the following format. No XML wrapper tags — the file content is the ledger body.
+
+**CRITICAL FORMAT RULES:**
+- `**Files**` MUST be followed by indented file paths on separate lines (not inline)
+- `**Details**` MUST be followed by indented bullet points on separate lines (not inline)
+- `**Dependency**` MUST be inline: `TSK-001-01` not on separate line
+
+**CRITICAL TASK ID CONSTRAINT:**
+- Task IDs MUST follow the format `TSK-{NNN}-{NN}:` where `NNN` is the 3-digit issue number and `NN` is the 2-digit task index within the issue, starting from `TSK-001-01:`.
+- Examples of VALID task IDs: `TSK-001-01:`, `TSK-001-02:`, `TSK-002-01:`, `TSK-010-01:`, `TSK-099-01:`
+- Examples of INVALID task IDs (DO NOT use): `T001:`, `TASK_1:`, `T1:`, `T-001:`, `Task1:`, `TSK001:`
+- The post-script validator enforces this exact pattern: `TSK-` followed by exactly 3 digits, `-`, exactly 2 digits, and a colon.
+
+**TASK STRUCTURE CONSTRAINTS** — every task MUST contain:
+- **Type**: `Feature_Batch | Infra_Batch | Domain_Batch | Bugfix | Migration | Config`
+- **Mode**: `TDD | IMMEDIATE` (no default — apply the decision tree at step 4b)
+  - `TDD`: Full Red-Green-Refactor cycle. **Use for**: New business logic, state mutations, integration boundaries, or non-trivial acceptance criteria.
+  - `IMMEDIATE`: Execute directly without test-first. **Use for**: Trivial updates (config, docs, constants), pure refactoring with existing test coverage, or low-risk boilerplate where testing cost outweighs regression risk.
+- **Test Strategy**: `Sociable_Unit | Integration | Solitary_Unit` (required if Mode is TDD)
+- **Verification**: A **Deterministic CLI Command** (e.g., `pytest tests/unit/test_s3.py`).
+- **Estimated Time**: Time estimate in format `30-90 minutes` or `60 minutes`.
+- **Files**: List of absolute or project-relative paths (multi-line, indented, minimum 2 files).
+- **Details**: **CRITICAL** — Must contain 4-8 detailed bullet points with explicit R-G-R breakdown:
+  - **Red**: Specific test file, test cases to write, and assertions
+  - **Green**: Exact functions/methods to implement, signatures, and logic
+  - **Refactor**: Code quality improvements, pattern alignment
+  - **Edge Cases**: Error handling, boundary conditions
+  - **Acceptance**: Concrete "done" criteria beyond test passing
+- **Dependency**: (Optional) `T{NNN}` if this task requires another task to complete first (inline value).
+
+**DETAILS QUALITY RULES:**
+- Minimum 4 bullet points, maximum 8
+- For TDD tasks: MUST include at least one **Red** bullet with specific test case name and assertion
+- For TDD tasks: MUST include at least one **Green** bullet with function signature and logic
+- For IMMEDIATE tasks: Use **Implementation** instead of **Red**/**Green**
+- SHOULD include **Edge Cases** for error handling scenarios
+- SHOULD include **Acceptance** with concrete "done" criteria
+
+**FILE TRACEABILITY RULES:**
+- **Rationale** is REQUIRED on every task (prevents misaligned scope)
+- Must explain WHY each file in **Files** is being modified
+- Must tie each file to specific story identifiers and acceptance criteria from spec.md
+- Every file in **Files** MUST be justified in **Rationale**
+- Files without justification are flagged as potential scope creep
+
+**DETERMINISM RULES:**
+- **No Vibe Coding**: Any task without a `Verification` command is invalid.
+- **No Layered Tasks**: Reject any task that doesn't produce a testable outcome.
+- **No Vague Details**: Reject any task with fewer than 4 `Details` bullets. TDD tasks must have **Red**/**Green** markers; IMMEDIATE tasks must have **Implementation** markers.
+- **Path Integrity**: Use absolute paths for all cross-references.
+- **Test-First Enforcement**: Every TDD task's **Green** bullet MUST have a corresponding **Red** bullet that defines the test it passes. IMMEDIATE tasks are exempt (use **Implementation** instead).
+
+**OUTPUT TEMPLATE** — the complete file should follow this structure:
+```markdown
+# Implementation Tasks: {BRANCH_NAME}
+
+## Phase 1: <Feature Slice Name>
+**Goal**: <what capability this slice delivers>
+
+### Tasks
+
+- T001: <Description of Vertical Slice>
+  - **Type**: Feature_Batch
+  - **Mode**: TDD
+  - **Test Strategy**: Sociable_Unit
+  - **Verification**: `pytest tests/unit/test_s3.py`
+  - **Estimated Time**: 60 minutes
+  - **Files**:
+    - `path/to/file1.ts`
+    - `path/to/file2.ts`
+  - **Rationale**: <Why these files? Tie to specific story US_### and AC>
+  - **Details**:
+    - **Red**: Write failing test: `<test_name>()` with assertion that <expected>
+    - **Green**: Implement `<function>(<params>): <return>` with <logic>
+    - **Refactor**: <code quality improvement>
+    - **Edge Cases**: Handle <error scenario> by <action>
+    - **Acceptance**: <concrete done criteria>
+
+- T002: <Description>
+  - **Type**: Feature_Batch
+  - **Mode**: IMMEDIATE
+  - **Verification**: `npm run lint`
+  - **Estimated Time**: 30 minutes
+  - **Dependency**: T001
+  - **Files**:
+    - `path/to/file3.ts`
+  - **Rationale**: <Why these files?>
+  - **Details**:
+    - **Implementation**: Implement `<function>()` with <logic>
+    - **Refactor**: <improvement>
+    - **Acceptance**: <criteria>
+
+---
+
+## Implementation Strategy
+**Execution Order**:
+1. Phase 1 -> Phase 2 (Logical dependency order)
+
+**Critical Dependency Chains**:
+- T001 (Schema) must precede T002 (API)
+
+**Risk Hotspots**:
+- High coupling in `user.service.ts`
+
+**Merge Conflict Boundaries**:
+- Files touched by multiple phases: [list_files]
+
+---
+
+## Universal Test Constraints (ALL TASKS)
+
+- **Git Isolation Mandatory**: Any test that invokes git operations (init, add, commit, branch, worktree, checkout, log, status, push) MUST operate on a temporary directory initialized as a fresh git repo via `tmp_path` (pytest) or `tempfile.TemporaryDirectory`. Tests MUST NOT run git commands within the real repository's working tree.
+- **Implementation Pattern**: Use a shared `tmp_git_repo` fixture from `tests/conftest.py` (which calls `git init` inside `tmp_path` and configures a test user). Pass `repo=tmp_git_repo` to all git-interacting functions. Never reference `Path.cwd()` or the real repo root.
+- **Rationale**: Prevent accidental commits, branch creation, or state mutation in the actual project repo during test execution. All tests are TDD and run repeatedly; accidental mutations corrupt the development workflow.
+
+## Universal API Design Constraint (ALL CORE MODULES)
+
+Every git-interacting function in core modules MUST accept an optional `repo_path: Path | None = None` parameter. When `None`, default to `Path.cwd()`. This is the **sole enabler** of test isolation — without it, tests must use fragile `chdir` tricks or operate on the real repo.
+
+```python
+# DO: accept repo_path, default to cwd
+def find_repo_root(start_at: Path | None = None) -> Path:
+    start_at = start_at or Path.cwd()
+
+def stage_and_commit(message: str, files: list[Path], repo: Path | None = None) -> str:
+    repo = repo or Path.cwd()
+    subprocess.run(["git", "add", ...], cwd=repo, check=True)
+
+# DON'T: hard-code Path.cwd() or rely on ambient working directory
+def find_repo_root() -> Path:  # BAD — untestable
+    ...
+```
+
+**Consequence**: Every per-task Git Isolation block below is a specific instance of this universal constraint. If a task's `Green` section says to implement a function that runs git commands, that function **must** accept `repo_path`.
+```
+
+**Write the entire content directly to `<tasks_target>`** as the file's full content. No wrapping tags, no preamble, no postamble. The post-script reads the file and commits it.
+</format_contract>
+
+
+</output_format_schemas>
+
+<edge_case_handling>
+<case condition="Pre-script emits STATUS: NOT_IN_WORKTREE or STATUS: SPEC_NOT_FOUND">
+<action>Stop. The /deviate-shard phase must produce a valid spec-enriched issue file (or a spec.md must exist as fallback) before tasks can run. Surface the status to the human operator.</action>
+</case>
+<case condition="Pre-script emits STATUS: PLAN_NOT_FOUND">
+<action>Halt. The /deviate-plan phase must complete and produce plan.md before tasks can run. Surface the missing plan.md path to the human operator. Use `deviate tasks pre --force` only if you have a documented reason to bypass the prerequisite.</action>
+</case>
+<case condition="Issue file contains embedded ## User Stories Ledger and ## ATDD Acceptance Criteria sections">
+<action>Read spec from the issue file directly — this is the primary path. Do NOT look for a separate spec.md. Per spec AC-ADHOC-003-07, embedded sections take precedence over spec.md when both exist.</action>
+</case>
+<case condition="Issue file lacks embedded spec sections (no USER_STORIES_LEDGER or ATDD_ACCEPTANCE_CRITERIA)">
+<action>Fall back to reading the adjacent spec.md file in the same issue directory. This is the legacy path — log a notice that the issue file lacks embedded spec sections, then proceed with spec.md as the spec source.</action>
+</case>
+<case condition="Both issue file embedded sections AND spec.md exist">
+<action>Embedded sections take precedence per spec AC-ADHOC-003-07. Read from the issue file; ignore spec.md. Document the precedence decision in a note.</action>
+</case>
+<case condition="spec.md is empty or missing required sections (fallback path only)">
+<action>Halt with Failure_State: "Invalid spec source — missing required sections". Require human to run /deviate-shard first to produce a valid spec-enriched issue.</action>
+</case>
+<case condition="spec.md is missing or incomplete (fallback path only)">
+<action>Continue with available spec sections. Add `[WARNING]` to tasks touching undefined areas.</action>
+</case>
+<case condition="No test command available from spec source or constitution">
+<action>Generate Verification commands using repository conventions (pytest, npm test) as defaults. Document inferred commands in a note.</action>
+</case>
+<case condition="Circular dependencies detected between tasks">
+<action>Detect and reject; require human to resolve dependency graph before task generation.</action>
+</case>
+<case condition="Post-script rejects output">
+<action>Halt, fix the violations, and re-run the post-script.</action>
+</case>
+</edge_case_handling>
+
+<context>
+<user_input>
+$ARGUMENTS
+</user_input>
+</context>
+