---
paths: "src/claude/skills/**/*.md, src/claude/agents/**/*.md, src/claude/commands/**/*.md, .claude/skills/**/*.md, .claude/agents/**/*.md, .claude/commands/**/*.md"
---

# Spec File Write Protection Rule

**Purpose:** Prevent modification of skill phase specs, agent prompts, and operational framework files to satisfy test constraints during refactoring phases.
**Scope:** All spec-driven-dev phase files, agent definitions, and skill definitions in `src/`.
**Enforcement:** Prompt-level HALT trigger with AskUserQuestion escalation.

---

## Problem This Solves

During Phase 04 (Refactoring), tests may fail due to fragile assertions (e.g., character proximity windows). The test-folder-protection rule prevents modifying tests, but without spec-file protection, Claude's only option is to modify the spec to make tests pass. This creates a perverse incentive:

```
Tests fail → Can't modify tests (protected) → Modify spec instead → Spec degradation
```

This rule breaks that loop by protecting specs too, forcing Claude to HALT and report the test design issue.

---

## Protected Path Patterns

The following file patterns are under restricted-write protection during Phase 04 (Refactoring):

```
src/claude/skills/*/phases/*.md
src/claude/skills/*/SKILL.md
src/claude/skills/*/references/*.md
src/claude/agents/*.md
src/claude/commands/*.md
```

Any Write(), Edit(), or Update() operation targeting these patterns during Phase 04 triggers the HALT protocol below.

---

## HALT Trigger

**HALT immediately when ALL of the following are true:**

1. The current workflow phase is **Phase 04 (Refactoring)**
2. The target file matches any protected path pattern listed above
3. The operation is a Write(), Edit(), or Update() command
4. The modification **removes or shortens** existing operational content (RECORD lines, VERIFY blocks, Grep commands, EXECUTE blocks)

**When HALT fires:**
- Stop all file operations immediately
- Do NOT proceed with the edit
- Display: "HALT: Spec file modification during Phase 04 is prohibited. Spec content is authoritative — fix the tests, not the spec."
- Invoke AskUserQuestion to request explicit user approval

**Exception:** Modifications that ADD new content without removing existing content (e.g., adding a new step) may proceed without HALT, as they don't degrade existing operational behavior.

---

## Rationale

Spec-driven-dev phase files are **implementation specifications** — they define WHAT Claude should do at runtime. They are the source of truth for workflow behavior. Modifying them to satisfy test constraints inverts the relationship: tests should validate the spec, not dictate it.

This rule works in conjunction with:
- **test-folder-protection.md** — Prevents test modification during non-test phases
- **phase-gate-write.sh** — Enforces phase-appropriate file access

Together, they create a **dual protection**: neither tests nor specs can be modified to satisfy the other during refactoring. If both need changes, Claude must HALT and consult the user.

---

## References

- **STORY-571:** Incident where RECORD lines were removed from phase-09-feedback.md to satisfy fragile test proximity assertions
- **test-folder-protection.md:** `.claude/rules/workflow/test-folder-protection.md`
- **phase-gate-write.sh:** `.claude/hooks/phase-gate-write.sh`
