# Task-to-Agent Migration: Acceptance Test Scenarios

## Feature: task-to-agent-migration
## Type: Bug fix (regression tests for breaking change)
## Claude Code Version: v2.1.63+

---

## Context

Claude Code v2.1.63 renamed `Task` tool to `Agent` and removed `max_turns` from tool_input schema. This broke DES hooks:

1. Hook matchers with `"matcher": "Task"` stopped firing
2. `max_turns` validation always blocked (field absent from new schema)

### ADRs

| ADR | Change | Impact |
|-----|--------|--------|
| ADR-1 | Remove MaxTurnsPolicy from PreToolUseService | Unblocks all DES invocations |
| ADR-2 | Update hook matchers Task -> Agent | Restores hook firing |
| ADR-3 | SubagentStop unaffected | No changes needed |

---

## Test Files

| File | Scope | Scenarios |
|------|-------|-----------|
| `test_agent_tool_hook_processing.py` | Hook processes new Agent schema | 4 |
| `test_enforcement_ordering_without_max_turns.py` | Validation pipeline integrity | 3 |
| `test_plugin_matcher_migration.py` | Plugin generates correct matchers | 3 |
| **Total** | | **10** |

### Error/Edge Ratio: 5/10 (50%) -- exceeds 40% target

---

## Scenario Catalog

### File 1: Agent Tool Hook Processing

#### 1.1 Agent tool DES invocation allowed without max_turns [WALKING SKELETON]
- **Given**: Valid DES prompt, NO max_turns in tool_input (new Agent schema)
- **When**: PreToolUse hook processes the invocation
- **Then**: ALLOWED (exit 0), no max_turns error
- **Tags**: @walking_skeleton, @regression
- **ADR**: ADR-1

#### 1.2 Agent tool non-DES invocation passes through
- **Given**: No DES markers, no max_turns
- **When**: PreToolUse hook processes
- **Then**: ALLOWED (exit 0)
- **Tags**: @happy_path
- **ADR**: ADR-1

#### 1.3 Agent tool invalid DES prompt still blocked [ERROR PATH]
- **Given**: DES markers present but missing mandatory sections, no max_turns
- **When**: PreToolUse hook processes
- **Then**: BLOCKED (exit 2), reason does NOT mention max_turns
- **Tags**: @error_path
- **ADR**: ADR-1

#### 1.4 Agent tool with legacy max_turns still works [EDGE CASE]
- **Given**: Valid DES prompt WITH max_turns=30 in tool_input (backward compat)
- **When**: PreToolUse hook processes
- **Then**: ALLOWED (exit 0), max_turns ignored
- **Tags**: @edge_case, @backward_compat
- **ADR**: ADR-1

### File 2: Enforcement Ordering Without max_turns

#### 2.1 Enforcement fires before completeness [ERROR PATH]
- **Given**: Prompt with step-id pattern, NO DES markers, NO max_turns
- **When**: Hook processes
- **Then**: BLOCKED with DES_MARKERS_MISSING (not max_turns error)
- **Tags**: @error_path, @ordering
- **ADR**: ADR-1

#### 2.2 Completeness check runs for DES tasks [ERROR PATH]
- **Given**: DES prompt with markers but missing mandatory sections
- **When**: Hook processes
- **Then**: BLOCKED by completeness/template validation (not max_turns)
- **Tags**: @error_path
- **ADR**: ADR-1

#### 2.3 Valid DES prompt allowed without max_turns
- **Given**: Fully valid DES prompt, no max_turns
- **When**: Hook processes
- **Then**: ALLOWED (exit 0)
- **Tags**: @happy_path
- **ADR**: ADR-1

### File 3: Plugin Matcher Migration

#### 3.1 DES plugin generates Agent matcher for PreToolUse [WALKING SKELETON]
- **Given**: DES installation plugin
- **When**: Generates PreToolUse hook config
- **Then**: Matcher is "Agent" (not "Task")
- **Tags**: @walking_skeleton, @regression
- **ADR**: ADR-2

#### 3.2 DES plugin generates Agent matcher for PostToolUse [ERROR PATH if wrong]
- **Given**: DES installation plugin
- **When**: Generates PostToolUse hook config
- **Then**: Matcher is "Agent" (not "Task")
- **Tags**: @regression
- **ADR**: ADR-2

#### 3.3 SubagentStop hook has no matcher [BOUNDARY]
- **Given**: DES installation plugin
- **When**: Generates SubagentStop hook config
- **Then**: Hook has no matcher (fires for all stops)
- **Tags**: @boundary, @unchanged
- **ADR**: ADR-3

---

## Mandate Compliance Evidence

### CM-A: Driving Port Usage
All test files import through driving ports only:
- `test_agent_tool_hook_processing.py`: `handle_pre_tool_use` (hook adapter entry point)
- `test_enforcement_ordering_without_max_turns.py`: `handle_pre_tool_use` (hook adapter entry point)
- `test_plugin_matcher_migration.py`: `DESPlugin._install_des_hooks` (plugin installation entry point)

No internal component imports (validators, parsers, policies).

### CM-B: Business Language
Test names and docstrings use domain terms:
- "invocation allowed", "passes through", "still blocked", "backward compat"
- Zero HTTP verbs, status codes, or infrastructure terms in test names

### CM-C: Scenario Counts
- Walking skeletons: 2 (test 1.1, test 3.1)
- Focused scenarios: 8 (remaining tests)
- Error paths: 5/10 = 50%

---

## Implementation Sequence

Enable one test at a time, implement, commit:

1. `test_agent_tool_des_invocation_allowed_without_max_turns` -- KEY regression
2. `test_agent_tool_non_des_invocation_passes_through` -- passthrough preserved
3. `test_agent_tool_invalid_des_prompt_still_blocked` -- other validations intact
4. `test_agent_tool_with_legacy_max_turns_still_works` -- backward compat
5. `test_enforcement_fires_before_completeness` -- ordering correct
6. `test_completeness_check_runs_for_des_tasks` -- completeness still works
7. `test_valid_des_prompt_allowed_without_max_turns` -- full pipeline pass
8. `test_des_plugin_generates_agent_matcher_for_pre_tool_use` -- matcher updated
9. `test_des_plugin_generates_agent_matcher_for_post_tool_use` -- post matcher
10. `test_subagent_stop_hook_has_no_matcher` -- unchanged behavior
