# Transform Rules — `{FROM_PATTERN}` → `{TO_PATTERN}`

<!--
  Populated by the orchestrator + user in Phase 03 from intent.json + classification.md.
  Schema reference: references/transform-rules-schema.md (5 required sections, in order).
  Every Phase 04 cluster worker Reads this file BEFORE any Edit.
-->

## Migration Intent

| Field | Value |
|-------|-------|
| `from_pattern` | `{FROM_PATTERN}` |
| `to_pattern`   | `{TO_PATTERN}` |
| `to_type`      | `file` \| `folder` \| `cli` |
| `scope_dirs`   | `["{SCOPE_DIR_1}", "{SCOPE_DIR_2}", …]` |
| `exclusions`   | `["{EXCLUSION_1}", "{EXCLUSION_2}", …]` |

---

## Dual-Path Protocol

| Operational copy | Canonical copy |
|------------------|----------------|
| `.claude/X/Y` | `src/claude/X/Y` |

**Rule:** For every `Edit(file_path=".claude/X/Y", old_string=…, new_string=…)`, apply the IDENTICAL `old_string` and IDENTICAL `new_string` to `src/claude/X/Y` in the same logical step. Verify with `Bash("diff .claude/X/Y src/claude/X/Y")` — output MUST be empty before the worker returns its report.

<!-- For a single-path migration, replace this section with: -->
<!-- "Single-path migration: dual-path protocol NOT applicable. Tree edited: {TREE}." -->

---

## Per-Bucket Transformation Directives

### Bucket: READ-OP

**Disposition:** TRANSFORM

**Transformation:**
`{find pattern}`  →  `{replacement pattern}`

**Examples:**
- BEFORE: `Read(file_path="…{FROM_PATTERN}")`
- AFTER:  `Read(file_path="…{TO_PATTERN_TARGET}")`

### Bucket: LISTING

**Disposition:** TRANSFORM (noun-swap only)

**Transformation:**
`{FROM_PATTERN}`  →  `{TO_PATTERN}`

### Bucket: PATH-VALIDATION

**Disposition:** TRANSFORM (noun-swap; orchestrator may recommend CLI-replacement prose if applicable)

**Transformation:**
`{FROM_PATTERN}`  →  `{TO_PATTERN}`

### Bucket: DOC

**Disposition:** TRANSFORM current-state prose; LEAVE DOC-historical prose.

**Transformation (current-state):**
`{FROM_PATTERN}`  →  `{TO_PATTERN}`

**DOC-historical sub-disposition:** LEAVE — historical records must read true at the time they were written (changelog entries, MIGRATION-NOTES rows, STORY-NNN provenance prose).

### Bucket: ALREADY-MIGRATED

**Disposition:** LEAVE.

(Text already explains the migration / cites the new artifact + the ADR. Editing corrupts the explanation.)

### Bucket: EXCLUDED

**Disposition:** LEAVE (file is out of migration scope — workers never open these.)

<!-- Add migration-specific buckets below if Phase 03 discussion required one
     (e.g. TEMPLATE-EXCLUDED, TEST-FIXTURE, URL-CITATION). See classification-bucket-catalog.md
     "Extending with Migration-Specific Buckets". -->

---

## Type-Change-Bug Declaration

**Type transition:** `{FROM_TYPE}` → `{TO_TYPE}`.

**FLAG-do-not-transform rule:** Cluster workers FLAG (NOT transform) any occurrence whose surrounding code reads the noun's type, not just its value. Categories workers MUST flag:

1. `Glob("…{FROM_PATTERN}…*.md")` count/existence checks (folder won't match `*.md`).
2. `[ -f path ]` shell tests on `{FROM_PATTERN}` (directory fails `-f` — recommend `[ -d ]`).
3. "the X section of `{FROM_PATTERN}`" content-greps when X doesn't exist in the new artifact.
4. `Read(file_path="…{FROM_PATTERN}")` whose target file's content was redistributed.

<!-- For a no-type-change migration (to_type == file), replace this section with: -->
<!-- "No type change; FLAG categories not applicable to this migration." -->

---

## Exclusions

- `{EXCLUSION_1}` — `{one-line reason}`
- `{EXCLUSION_2}` — `{one-line reason}`

<!-- Workers re-grep their cluster's SCOPE_DIRS and drop any hit matching any pattern above. -->
