---
paths: "tests/**, **/*.test.*, **/*.spec.*, **/test_*.py, **/*_test.py"
---

# Test Folder Write Protection Rule

**Purpose:** Restrict write access to test files to only authorized subagents during their designated workflow phases.
**Scope:** All files under `tests/` directory and co-located test files.
**Enforcement:** `phase-gate-write.sh` hook (phase dimension, `exit 2`) + prompt-level check (agent-authorization dimension).

---

## Protected Path Patterns

The following file patterns are under restricted-write protection:

```
tests/**
*.test.*
*.spec.*
test_*.py
*_test.py
```

Any Write(), Edit(), or file creation operation targeting these patterns is governed by the enforcement rules below.

---

## Enforcement

`phase-gate-write.sh` (PreToolUse[Edit|Write]) hard-blocks test-file writes with
`exit 2` when the current phase does not permit them — see the Phase-Specific
Behavior table below. `exit 2` cannot be rationalized past.

The hook enforces the **phase** dimension. It cannot see **which agent** is
writing, so the agent-authorization dimension stays a prompt-level check — a
test-file write is a violation when ALL of the following hold:

1. The active agent is **not authorized** for the current workflow phase (see Authorized Agents below)
2. The operation targets a file matching a Protected Path Pattern above
3. The operation is a Write(), Edit(), or file creation command

**Non-authorized agents include:** orchestrator (opus), backend-architect, frontend-developer, refactoring-specialist, code-reviewer, documentation-writer, and any other agent not listed in Authorized Agents below. Any unauthorized agent attempting to modify test files MUST be stopped — this prevents silent test tampering that could mask implementation defects. When a write is blocked, recover via the AskUserQuestion Protocol below.

---

## Authorized Agents

The following agents are permitted to write to test files during their designated phases ONLY:

| Agent | Phase | Authorization |
|-------|-------|---------------|
| **test-automator** | Phase 02 (Red) | Authorized and permitted to write test files during TDD Red phase |
| **integration-tester** | Phase 05 (Integration) | Authorized and permitted to write integration test files during Integration phase |

**Phase-specific restrictions:**
- test-automator is ONLY authorized during Phase 02. Writing tests during Phase 03, 04, or any other phase requires user approval.
- integration-tester is ONLY authorized during Phase 05. Writing tests during any other phase requires user approval.
- No agent has blanket authorization across all phases.

---

## AskUserQuestion Protocol

When a non-authorized agent attempts to modify test files, invoke AskUserQuestion with the following format:

```
AskUserQuestion:
  Question: "{agent_name} is attempting to modify test file: {file_path}. Test files should only be modified by authorized subagents during their designated phases."
  Header: "Test Protection"
  Options:
    - label: "Return to Phase 02 (Recommended)"
      description: "Re-enter Phase 02, invoke test-automator to regenerate tests with the fix, update red-phase checksum snapshot, then resume from Phase 03"
    - label: "Approve direct modification"
      description: "Grant one-time permission for this specific file change. WARNING: This will cause test checksum mismatch and may trigger TEST TAMPERING in QA."
    - label: "Deny and HALT"
      description: "Block the modification and stop the current operation"
  multiSelect: false
```

**Option Processing:**

| Option | Action |
|--------|--------|
| **Return to Phase 02** | Reset phase state to 02 via `devforgeai-validate phase-reset ${STORY_ID} --to=02`. Re-invoke test-automator with context about the bug to fix. After test-automator regenerates tests, re-create red-phase checksum snapshot. Resume from Phase 03. |
| **Approve direct modification** | Proceed with Write()/Edit(). Log modification in story Implementation Notes under `### Authorized Test Modifications`. Note: QA will flag checksum mismatch — this approval does NOT suppress QA findings. |
| **Deny and HALT** | Block the modification and stop the current operation. |

**The orchestrator MUST NOT select on behalf of the user.** Present all three options and wait for explicit user choice.

**Scope of approval:** Each approval covers a single file operation. Subsequent modifications to test files by the same non-authorized agent require separate approval.

---

## Phase-Specific Behavior

| Phase | Behavior |
|-------|----------|
| Phase 01 (Pre-Flight) | No test writes expected. HALT if attempted. |
| Phase 02 (Red) | test-automator writes freely. All other agents HALT. |
| Phase 03 (Green) | All test writes HALT + AskUserQuestion. |
| Phase 04 (Refactor) | All test writes HALT + AskUserQuestion. Prevents test tampering masquerading as refactoring. |
| Phase 05 (Integration) | integration-tester writes freely. All other agents HALT. |
| Phase 06-10 | No test writes expected. HALT if attempted. |

---

## Rationale

Test integrity is a critical quality gate in the DevForgeAI TDD workflow. If tests are modified outside designated phases by unauthorized agents, defects can be masked:

- **Phase 03 risk:** Implementation agents could weaken test assertions to make failing tests pass
- **Phase 04 risk:** Refactoring agents could delete or simplify tests that catch regressions
- **Silent tampering:** Without this rule, test modifications go undetected until QA validation

This rule works in conjunction with:
- **STORY-502:** Red-phase test integrity checksums (detection-based backup)
- **STORY-503:** Test tampering heuristic patterns (pattern-based detection)

---

## References

- **EPIC-085:** QA Diff Regression Detection and Test Integrity System
- **ADR-025:** QA Diff Regression Detection
- **STORY-502:** Red-Phase Test Integrity Checksums
- **STORY-503:** Test Tampering Heuristic Patterns
