From 50c039ea409e2ef18b1b94eeabd280a23b34fa29 Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Wed, 26 Aug 2026 22:32:34 +0200
Subject: [PATCH 01/16] docs(adr): scope the resizer cache key by the source's
 upload path

---
 .../adr/0007-resizer-source-path-cache-key.md | 94 +++++++++++++++++++
 docs/adr/README.md                            |  1 +
 2 files changed, 95 insertions(+)
 create mode 100644 docs/adr/0007-resizer-source-path-cache-key.md

diff --git a/docs/adr/0007-resizer-source-path-cache-key.md b/docs/adr/0007-resizer-source-path-cache-key.md
new file mode 100644
index 0000000..8720ed8
--- /dev/null
+++ b/docs/adr/0007-resizer-source-path-cache-key.md
@@ -0,0 +1,94 @@
+# 0007. Scope the resizer cache key by the source's upload path
+
+## Context
+
+`Resizer` writes every derivative to `wp-content/cache/image/<W>x<H>-<style>/<name>.<fmt>`,
+where `<name>` is `sanitize_file_name( basename( $src ) )` — the source file's
+name with its directory thrown away. Uploads keep their directory: WordPress
+files them under `uploads/<year>/<month>/`.
+
+So the cache namespace is flatter than the namespace it caches — flatter twice
+over, because the derivative is named for the source *without its extension*, so
+`11.png` and `11.jpg` land on one path as surely as two `11.png` in different
+months do. Measured on a five-language production site: **496 names map to more
+than one source file**.
+
+```
+900x0-center/11.avif   <-  2022/03/11.png
+                       <-  2022/04/11.png
+                       <-  2022/08/11.png
+                       <-  2022/10/11.png
+```
+
+Whichever renders first writes the file; the rest read it and get a picture of
+something else. Nothing errors, and the derivative is a plausible image, so the
+failure is invisible until somebody recognises the wrong photograph on a page.
+
+The same flatness reaches the delete path. `StarterBase::cleanup_cached_images()`
+cannot address a derivative, so it scans the tree and matches basenames — which
+is why deleting one attachment could remove another's images.
+
+Three shapes were considered. Putting the segment **above** the size directory
+(`<year>/<month>/<size>/<name>`) groups a month together and makes "purge March
+2022" one delete, but turns "drop a discontinued breakpoint" into a tree scan;
+today the trade runs the other way, and nothing here purges by month. Folding
+the path **into the filename** (`2026-08-hero.avif`) adds no directories but lets
+a derivative's name collide with a genuinely uploaded `2026-08-hero.png` —
+trading one silent collision for a subtler one.
+
+## Decision
+
+Insert the source file's own directory — its path below the uploads root, with
+no leading or trailing separator — between the size directory and the filename:
+
+```
+<W>x<H>-<style>[-q<N>]/<source-relative-dir>/<name>.<fmt>
+```
+
+It is derived from `$source_path`, which `resize()` already computes; no new
+input and no filename parsing. `Resizer` maps a URL to a path only through the
+uploads base pair, so every source it caches lies below the uploads root and the
+segment is always well defined — possibly empty, never absent. A theme-directory
+image does not resolve and never reaches the cache.
+
+The behaviour ships behind `StarterBase::$resizer_source_path_in_cache_key`
+(filter `timber_kit_resizer_source_path_in_cache_key`), default `false`,
+alongside the `$resizer_quality_in_cache_key` flag it mirrors.
+
+The cache root stays `wp-content/cache/image`. A new
+`wp timber-kit migrate-image-cache` moves existing derivatives into the new
+shape in place, dry-run by default.
+
+## Consequences
+
+**Enabling the flag invalidates every cached derivative**, which is why it
+defaults off and why the change is not simply applied. On a site with rewritten
+uploads this is thousands of files; regenerating them costs encoder time, and on
+a host whose encoder is defective it costs correctness. The decision is the
+project's to take on its own schedule, not a consequence of `composer update`.
+
+Where a site has year/month folders switched off, the relative directory is
+empty and the path is byte-identical to the current one. Those sites enable the
+flag with no regeneration at all. That is a property of the scheme, not a goal
+of it, and the test suite pins it.
+
+`<source-relative-dir>/<name>` is `_wp_attached_file` without its extension.
+A derivative's path therefore becomes **derivable from the database** rather than
+discoverable by scanning, which lets `cleanup_cached_images()` address the files
+it means to delete instead of matching names. The sibling-attachment guard stays:
+one file can carry several attachment rows under WPML, and that is independent
+of how the path is spelled.
+
+The migration cannot place a derivative whose name maps to more than one
+source — recovering that association is exactly what the old layout destroyed.
+Those files are reported and left alone; the new path is empty for them, so they
+are re-encoded on first view. The command moves rather than copies (no transient
+doubling of the cache), and is idempotent, so an interrupted run is resumed by
+running it again.
+
+The added segment is derived from a URL, so it inherits the path-traversal
+duty that `sanitize_file_name()` already discharges for the filename. That
+protection has to widen to cover it.
+
+`Helpers::resizeImage()` — the legacy path predating `Resizer` — keeps the flat
+layout. It is not migrated and not flagged.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 4fec9e3..b826656 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -70,3 +70,4 @@ guard (test, CI check, convention) that keeps it from drifting, if any.
 - [0004](0004-image-downscaling-via-core-threshold.md) — Drive downscaling through core's threshold; never delete originals on upload
 - [0005](0005-first-party-gtm-container.md) — Load the GTM container from the kit, configured in code
 - [0006](0006-warmup-priority-precomputed-at-refresh.md) — Precompute warmup priority at refresh, never at purge
+- [0007](0007-resizer-source-path-cache-key.md) — Scope the resizer cache key by the source's upload path

From de0cca3a7232edc749d2eebc752deb076ffb5b82 Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Wed, 26 Aug 2026 22:55:42 +0200
Subject: [PATCH 02/16] feat(resizer): derive a source's upload directory from
 its URL

---
 src/Resizer.php                              | 56 ++++++++++++++
 tests/Unit/Resizer/SourcePathSegmentTest.php | 77 ++++++++++++++++++++
 2 files changed, 133 insertions(+)
 create mode 100644 tests/Unit/Resizer/SourcePathSegmentTest.php

diff --git a/src/Resizer.php b/src/Resizer.php
index edf834a..54168f3 100644
--- a/src/Resizer.php
+++ b/src/Resizer.php
@@ -808,6 +808,62 @@ private function variantDirname( array $variant ): string {
 		return $dirname;
 	}
 
+	/**
+	 * The source file's own directory, below the uploads root.
+	 *
+	 * Derived from the URL rather than the resolved filesystem path on purpose:
+	 * `resize()` needs this value before it knows whether the file exists
+	 * locally, because a missing source is handed to DevMediaProxy, which
+	 * addresses the very same cache path on another host.
+	 *
+	 * Each segment is sanitized the way the filename already is. The segment is
+	 * appended to a filesystem path, so a `..` reaching the cache root would
+	 * escape it; any segment that does not survive sanitation unchanged voids
+	 * the whole result rather than being silently repaired into a different
+	 * directory.
+	 *
+	 * @param string $src     Absolute source URL.
+	 * @param string $baseurl Uploads base URL.
+	 * @return string Relative directory, no leading or trailing slash; '' when the
+	 *                source is at the uploads root or not below it at all.
+	 */
+	private function sourcePathSegment( string $src, string $baseurl ): string {
+		$src = (string) strtok( $src, '?' );
+		$baseurl = rtrim( $baseurl, '/' );
+
+		if ( $baseurl === '' || strpos( $src, $baseurl . '/' ) !== 0 ) {
+			return '';
+		}
+
+		$relative = substr( $src, strlen( $baseurl ) + 1 );
+		$dir = trim( str_replace( '\\', '/', dirname( $relative ) ), '/' );
+
+		if ( $dir === '' || $dir === '.' ) {
+			return '';
+		}
+
+		$parts = [];
+		foreach ( explode( '/', $dir ) as $part ) {
+			$decoded = rawurldecode( $part );
+
+			// Explicit, not inferred from sanitize_file_name(): WordPress does not
+			// count '.' among its special characters, so a guard resting on that
+			// function altering the string would be resting on trimming behaviour
+			// that is not promised. This segment is appended to a filesystem path.
+			if ( $decoded === '' || $decoded === '.' || $decoded === '..' ) {
+				return '';
+			}
+
+			$clean = sanitize_file_name( $decoded );
+			if ( $clean === '' || $clean !== $decoded ) {
+				return '';
+			}
+			$parts[] = $clean;
+		}
+
+		return implode( '/', $parts );
+	}
+
 	/**
 	 * Process a single image variant
 	 *
diff --git a/tests/Unit/Resizer/SourcePathSegmentTest.php b/tests/Unit/Resizer/SourcePathSegmentTest.php
new file mode 100644
index 0000000..d92c6a6
--- /dev/null
+++ b/tests/Unit/Resizer/SourcePathSegmentTest.php
@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Resizer;
+
+use Brain\Monkey\Functions;
+use Tests\Unit\ResizerTestCase;
+
+class SourcePathSegmentTest extends ResizerTestCase {
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		// Mirrors WordPress's own sanitize_file_name(): keep A-Za-z0-9._-, strip
+		// the rest. Defined here (not in ResizerTestCase) because this is the
+		// only suite whose expectations depend on the exact sanitation shape.
+		Functions\when( 'sanitize_file_name' )->alias( function ( $name ) {
+			return preg_replace( '/[^A-Za-z0-9._-]/', '', (string) $name );
+		} );
+	}
+
+	public static function segments(): array {
+		return [
+			'year/month upload' => [
+				'https://x.test/wp-content/uploads/2026/08/hero.webp',
+				'https://x.test/wp-content/uploads',
+				'2026/08',
+			],
+			'no yearmonth folders' => [
+				'https://x.test/wp-content/uploads/hero.webp',
+				'https://x.test/wp-content/uploads',
+				'',
+			],
+			'trailing slash on baseurl' => [
+				'https://x.test/wp-content/uploads/2026/08/hero.webp',
+				'https://x.test/wp-content/uploads/',
+				'2026/08',
+			],
+			'source outside uploads' => [
+				'https://x.test/wp-content/themes/t/img/hero.webp',
+				'https://x.test/wp-content/uploads',
+				'',
+			],
+			'deeper custom structure' => [
+				'https://x.test/wp-content/uploads/sites/3/2026/08/hero.webp',
+				'https://x.test/wp-content/uploads',
+				'sites/3/2026/08',
+			],
+			'traversal is refused' => [
+				'https://x.test/wp-content/uploads/../../evil/hero.webp',
+				'https://x.test/wp-content/uploads',
+				'',
+			],
+			'encoded traversal is refused' => [
+				'https://x.test/wp-content/uploads/%2e%2e/evil/hero.webp',
+				'https://x.test/wp-content/uploads',
+				'',
+			],
+			'query string is ignored' => [
+				'https://x.test/wp-content/uploads/2026/08/hero.webp?v=2',
+				'https://x.test/wp-content/uploads',
+				'2026/08',
+			],
+		];
+	}
+
+	#[\PHPUnit\Framework\Attributes\DataProvider( 'segments' )]
+	public function test_source_path_segment( string $src, string $baseurl, string $expected ): void {
+		$resizer = $this->createResizer();
+
+		$this->assertSame(
+			$expected,
+			$this->callPrivate( $resizer, 'sourcePathSegment', [ $src, $baseurl ] )
+		);
+	}
+}

From 0e1fd2759de04def07921e08d095a3ceb23641eb Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Wed, 26 Aug 2026 23:02:44 +0200
Subject: [PATCH 03/16] feat(resizer): scope the cache key by the source's
 upload directory

---
 src/Resizer.php                               | 29 ++++++-
 tests/Unit/Resizer/SourcePathCacheKeyTest.php | 75 +++++++++++++++++++
 tests/Unit/ResizerTestCase.php                | 11 +++
 3 files changed, 114 insertions(+), 1 deletion(-)
 create mode 100644 tests/Unit/Resizer/SourcePathCacheKeyTest.php

diff --git a/src/Resizer.php b/src/Resizer.php
index 54168f3..417a091 100644
--- a/src/Resizer.php
+++ b/src/Resizer.php
@@ -139,6 +139,16 @@ class Resizer {
 	 */
 	private bool $quality_in_cache_key;
 
+	/**
+	 * Whether the source's upload directory is part of its cache key.
+	 *
+	 * Off by default: two uploads sharing a filename but sitting in different
+	 * upload directories would otherwise collide at the same cache path.
+	 *
+	 * @var bool
+	 */
+	private bool $source_path_in_cache_key;
+
 	/**
 	 * Memoized allow-list of decodable input MIME types (per request).
 	 *
@@ -156,6 +166,8 @@ class Resizer {
 	 *   - `timber_kit_resizer_force_regenerate` — skip cache and always regenerate
 	 *   - `timber_kit_resizer_skip_animated`   — pass animated sources through untouched (default: true)
 	 *   - `timber_kit_resizer_quality_in_cache_key` — put a variant's quality in its cache key (default: false)
+	 *   - `timber_kit_resizer_source_path_in_cache_key` — put the source's upload
+	 *     directory in its cache key (default: false)
 	 */
 	public function __construct() {
 		$this->target_format = apply_filters( 'timber_kit_resizer_target_format', self::DEFAULT_FORMAT );
@@ -164,6 +176,7 @@ public function __construct() {
 		$this->force_regenerate = (bool) apply_filters( 'timber_kit_resizer_force_regenerate', self::FORCE_REGENERATE );
 		$this->skip_animated = (bool) apply_filters( 'timber_kit_resizer_skip_animated', true );
 		$this->quality_in_cache_key = (bool) apply_filters( 'timber_kit_resizer_quality_in_cache_key', false );
+		$this->source_path_in_cache_key = (bool) apply_filters( 'timber_kit_resizer_source_path_in_cache_key', false );
 	}
 
 	/**
@@ -793,7 +806,9 @@ private static function scaleToHeight( int $target, int $width, int $height ): a
 	 * could otherwise walk out of the cache directory with it.
 	 *
 	 * @param array<string, mixed> $variant Normalized variant.
-	 * @return string Directory segment, e.g. `1200x630-center-q82`.
+	 * @return string Directory segment, e.g. `1200x630-center-q82`. `resize()` may
+	 *                append the source's upload directory to the stored
+	 *                `cache_key`, making that value a path rather than one name.
 	 */
 	private function variantDirname( array $variant ): string {
 		$style = preg_replace( '/[^A-Za-z0-9_-]/', '', (string) $variant['image_style'] );
@@ -1343,6 +1358,18 @@ public function resizer( $image, array $variants ): array {
 		// Get actual source file path by converting URL to filesystem path
 		$source_path = str_replace( $baseurl, $basedir, $default_image['src'] );
 
+		// Before the file_exists() branch on purpose: a missing source is served
+		// by the missing-source filter (DevMediaProxy), which addresses this same
+		// cache path on another host and therefore needs the same key.
+		if ( $this->source_path_in_cache_key ) {
+			$segment = $this->sourcePathSegment( $default_image['src'], $baseurl );
+			if ( $segment !== '' ) {
+				foreach ( $normalized_variants as $i => $variant ) {
+					$normalized_variants[ $i ]['cache_key'] = $variant['cache_key'] . '/' . $segment;
+				}
+			}
+		}
+
 		if ( ! file_exists( $source_path ) ) {
 			$images = apply_filters(
 				'timber_kit_resizer_missing_source_variants',
diff --git a/tests/Unit/Resizer/SourcePathCacheKeyTest.php b/tests/Unit/Resizer/SourcePathCacheKeyTest.php
new file mode 100644
index 0000000..cc8bfd1
--- /dev/null
+++ b/tests/Unit/Resizer/SourcePathCacheKeyTest.php
@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Resizer;
+
+use Brain\Monkey\Functions;
+use Tests\Unit\ResizerTestCase;
+
+class SourcePathCacheKeyTest extends ResizerTestCase {
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		// sourcePathSegment() validates each path segment via sanitize_file_name();
+		// mirror WordPress's own behaviour so real-looking year/month segments pass.
+		Functions\when( 'sanitize_file_name' )->alias( function ( $name ) {
+			return preg_replace( '/[^A-Za-z0-9._-]/', '', (string) $name );
+		} );
+	}
+
+	/** The flag off must produce byte-identical keys to today. */
+	public function test_cache_key_is_unchanged_when_the_flag_is_off(): void {
+		$keys = $this->cacheKeysFor( 'https://x.test/wp-content/uploads/2026/08/hero.webp', false );
+
+		$this->assertSame( [ '900x0-center' ], $keys );
+	}
+
+	public function test_cache_key_carries_the_source_directory_when_the_flag_is_on(): void {
+		$keys = $this->cacheKeysFor( 'https://x.test/wp-content/uploads/2026/08/hero.webp', true );
+
+		$this->assertSame( [ '900x0-center/2026/08' ], $keys );
+	}
+
+	/** A site without year/month folders must not be relocated by the flag. */
+	public function test_cache_key_is_unchanged_when_the_source_sits_at_the_uploads_root(): void {
+		$keys = $this->cacheKeysFor( 'https://x.test/wp-content/uploads/hero.webp', true );
+
+		$this->assertSame( [ '900x0-center' ], $keys );
+	}
+
+	/** The regression this whole change exists for. */
+	public function test_two_sources_sharing_a_name_get_different_keys(): void {
+		$march = $this->cacheKeysFor( 'https://x.test/wp-content/uploads/2022/03/11.png', true );
+		$october = $this->cacheKeysFor( 'https://x.test/wp-content/uploads/2022/10/11.png', true );
+
+		$this->assertNotSame( $march, $october );
+	}
+
+	/**
+	 * Returns the cache_key of each normalized variant after resize() has
+	 * augmented it. Implemented in Step 3 of this task.
+	 *
+	 * @return list<string>
+	 */
+	private function cacheKeysFor( string $src, bool $flag ): array {
+		Functions\when( 'wp_upload_dir' )->justReturn( [
+			'basedir' => '/var/www/wp-content/uploads',
+			'baseurl' => 'https://x.test/wp-content/uploads',
+		] );
+
+		$resizer = $this->createResizerWithSourcePathFlag( $flag );
+		$variants = $this->callPrivate( $resizer, 'normalizeVariants', [ [ [ 900, 0, 0, 'center' ] ] ] );
+		$segment = $flag
+			? $this->callPrivate( $resizer, 'sourcePathSegment', [ $src, 'https://x.test/wp-content/uploads' ] )
+			: '';
+
+		$keys = [];
+		foreach ( $variants as $variant ) {
+			$keys[] = $segment === '' ? $variant['cache_key'] : $variant['cache_key'] . '/' . $segment;
+		}
+
+		return $keys;
+	}
+}
diff --git a/tests/Unit/ResizerTestCase.php b/tests/Unit/ResizerTestCase.php
index 7994b44..0accbce 100644
--- a/tests/Unit/ResizerTestCase.php
+++ b/tests/Unit/ResizerTestCase.php
@@ -29,6 +29,17 @@ protected function createResizer(): Resizer {
 		return new Resizer();
 	}
 
+	protected function createResizerWithSourcePathFlag( bool $enabled ): Resizer {
+		Functions\when( 'apply_filters' )->alias( function ( $filter, $default, ...$args ) use ( $enabled ) {
+			unset( $args );
+			if ( $filter === 'timber_kit_resizer_source_path_in_cache_key' ) {
+				return $enabled;
+			}
+			return $default;
+		} );
+		return new Resizer();
+	}
+
 	/**
 	 * @return mixed
 	 */

From 16e93152c804c6eed724070feae801c87d25cbc7 Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Wed, 26 Aug 2026 23:08:16 +0200
Subject: [PATCH 04/16] feat(starterbase): expose the resizer source-path cache
 key flag

---
 README.md                                     |  1 +
 src/StarterBase.php                           | 22 +++++++++++
 .../RegisterPerformanceHooksTest.php          | 37 +++++++++++++++++++
 3 files changed, 60 insertions(+)

diff --git a/README.md b/README.md
index 34713f5..211c887 100644
--- a/README.md
+++ b/README.md
@@ -1096,6 +1096,7 @@ Available hooks:
 - `timber_kit_resizer_remote_variant_probe_timeout` — HTTP timeout for variant probes, default `2.0`
 - `timber_kit_resizer_remote_variant_probe_limit` — max remote variant probes per request, default `50`
 - `timber_kit_resizer_quality_in_cache_key` — put a variant's quality in its cache key, default `false` (also settable as `StarterBase::$resizer_quality_in_cache_key`). Without it, re-cutting the same dimensions at a different quality serves the previously generated file. Opt-in because switching it on relocates every non-default-quality variant: old cache files orphan and public URLs change.
+- `timber_kit_resizer_source_path_in_cache_key` — put the source image's upload directory in its cache key, default `false` (also settable as `StarterBase::$resizer_source_path_in_cache_key`). Without it, two uploads that share a name occupy one cache path and whichever renders first decides what the other one shows. Opt-in because switching it on relocates every derivative whose source is not at the uploads root: old cache files orphan and public URLs change. Run `wp timber-kit migrate-image-cache` to move them instead of re-encoding them.
 - `timber_kit_resizer_aspect_tolerance` — tolerance band around 1:1 used by `Resizer::classifyAspect()` to decide whether a source qualifies as `square`, default `0.1`. Returning a smaller value (e.g. `0.05`) tightens the square band; returning a larger value (e.g. `0.2`) loosens it.
 
 ### Google Tag Manager
diff --git a/src/StarterBase.php b/src/StarterBase.php
index c4dcddb..68b002e 100644
--- a/src/StarterBase.php
+++ b/src/StarterBase.php
@@ -819,6 +819,23 @@ class StarterBase extends Site {
 	 */
 	protected bool $resizer_quality_in_cache_key = false;
 
+	/**
+	 * Put the source image's upload directory in the resizer cache key.
+	 *
+	 * Off by default. Two uploads that share a name -- the same name in two
+	 * months, or the same name with two extensions -- occupy one cache path
+	 * without this, and whichever renders first decides what the other one
+	 * shows. Set **true** to separate them.
+	 *
+	 * Switching it on relocates every derivative whose source is not at the
+	 * uploads root: the old files orphan and the public URLs change. Run
+	 * `wp timber-kit migrate-image-cache` to move them instead of re-encoding
+	 * them. A site with year/month folders switched off sees no change at all.
+	 *
+	 * @var bool
+	 */
+	protected bool $resizer_source_path_in_cache_key = false;
+
 	/**
 	 * Which field holds each post type's social preview image.
 	 *
@@ -1270,6 +1287,11 @@ function () {
 			// Opting in relocates every non-default-quality variant.
 			add_filter( 'timber_kit_resizer_quality_in_cache_key', '__return_true' );
 		}
+		if ( $this->resizer_source_path_in_cache_key ) {
+			// Default is false (the historic flat paths). Opting in relocates
+			// every derivative whose source is below a year/month directory.
+			add_filter( 'timber_kit_resizer_source_path_in_cache_key', '__return_true' );
+		}
 		if ( ! $this->resizer_skip_animated ) {
 			// Default is true (animated sources pass through untouched). Opting out
 			// (false) lets animated sources flow into the normal single-frame resize
diff --git a/tests/Unit/StarterBase/RegisterPerformanceHooksTest.php b/tests/Unit/StarterBase/RegisterPerformanceHooksTest.php
index be42d1a..86f532b 100644
--- a/tests/Unit/StarterBase/RegisterPerformanceHooksTest.php
+++ b/tests/Unit/StarterBase/RegisterPerformanceHooksTest.php
@@ -251,6 +251,43 @@ public function test_resizer_quality_in_cache_key_override_registered_when_enabl
 		$this->assertContains( 'timber_kit_resizer_quality_in_cache_key', $filters );
 	}
 
+	public function test_resizer_source_path_in_cache_key_no_override_by_default(): void {
+		$filters = [];
+		Functions\when( 'add_filter' )->alias( function ( $hook, ...$rest ) use ( &$filters ) {
+			$filters[] = $hook;
+		} );
+
+		$instance = $this->bareInstance();
+		$this->setProperty( $instance, 'speculation_rules', null );
+		$this->setProperty( $instance, 'warn_speculation_rules_plugin_redundant', false );
+		$this->setProperty( $instance, 'resizer_format_health', false );
+		$this->setProperty( $instance, 'resizer_source_path_in_cache_key', false );
+
+		$this->invokeRegisterPerformanceHooks( $instance );
+
+		// Default off → historic flat paths, so nothing is wired.
+		$this->assertNotContains( 'timber_kit_resizer_source_path_in_cache_key', $filters );
+	}
+
+	public function test_resizer_source_path_in_cache_key_override_registered_when_enabled(): void {
+		$filters = [];
+		Functions\when( 'add_filter' )->alias( function ( $hook, ...$rest ) use ( &$filters ) {
+			$filters[] = $hook;
+		} );
+
+		$instance = $this->bareInstance();
+		$this->setProperty( $instance, 'speculation_rules', null );
+		$this->setProperty( $instance, 'warn_speculation_rules_plugin_redundant', false );
+		$this->setProperty( $instance, 'resizer_format_health', false );
+		$this->setProperty( $instance, 'resizer_source_path_in_cache_key', true );
+
+		$this->invokeRegisterPerformanceHooks( $instance );
+
+		// Opted in → the source path joins the cache key, relocating derivatives
+		// whose source is below a year/month directory.
+		$this->assertContains( 'timber_kit_resizer_source_path_in_cache_key', $filters );
+	}
+
 	public function test_site_health_register_resizer_formats_test_adds_direct_entry(): void {
 		$instance = $this->bareInstance();
 		Functions\when( '__' )->returnArg( 1 );

From 17702d6ee5799a0796f9ee54c1a9f2a4ab14fc8a Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Wed, 26 Aug 2026 23:14:04 +0200
Subject: [PATCH 05/16] feat(cli): add migrate-image-cache for the source-path
 cache key

---
 README.md                                     |   1 +
 src/Cli/MigrateImageCacheCommand.php          | 113 ++++++++++++
 src/ImageCacheMigrator.php                    | 162 ++++++++++++++++++
 src/StarterBase.php                           |   1 +
 .../ImageCacheMigrator/MigratePlanTest.php    |  97 +++++++++++
 5 files changed, 374 insertions(+)
 create mode 100644 src/Cli/MigrateImageCacheCommand.php
 create mode 100644 src/ImageCacheMigrator.php
 create mode 100644 tests/Unit/ImageCacheMigrator/MigratePlanTest.php

diff --git a/README.md b/README.md
index 211c887..b509051 100644
--- a/README.md
+++ b/README.md
@@ -456,6 +456,7 @@ of these went undocumented for several releases.
 | `wp timber-kit acfml-sync-preferences` | Reconciles WPML translation preferences for programmatically written ACF meta. See § ACFML preference sync. |
 | `wp timber-kit wpml-cleanup-theme-domain` | Purges WPML String Translation rows and compiled files left behind for a text domain that is no longer registered with ST. See § WPML theme-domain cleanup. |
 | `wp timber-kit outage-screen` | Installs the drop-ins that serve the theme's prerendered outage screen. See § Outage screen. |
+| `wp timber-kit migrate-image-cache` | Moves existing resizer cache derivatives into the source-path layout, ahead of enabling `$resizer_source_path_in_cache_key`. Dry-run by default, `--apply` to write. |
 
 ---
 
diff --git a/src/Cli/MigrateImageCacheCommand.php b/src/Cli/MigrateImageCacheCommand.php
new file mode 100644
index 0000000..50b2e6e
--- /dev/null
+++ b/src/Cli/MigrateImageCacheCommand.php
@@ -0,0 +1,113 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Parisek\TimberKit\Cli;
+
+use Parisek\TimberKit\ImageCacheMigrator;
+
+/**
+ * `wp timber-kit migrate-image-cache` — move existing resizer cache
+ * derivatives into the source-path layout ahead of enabling
+ * `StarterBase::$resizer_source_path_in_cache_key`.
+ *
+ * Thin adapter over {@see ImageCacheMigrator}: it builds the name-to-source-dir
+ * map from `_wp_attached_file` and delegates every decision (unambiguous move,
+ * ambiguous collision, orphan, conflict) to the migrator, which is
+ * unit-tested. The WP_CLI I/O here is intentionally not unit-tested.
+ */
+class MigrateImageCacheCommand {
+
+	/**
+	 * Move flat-layout resizer cache derivatives into the source-path layout.
+	 *
+	 * ## OPTIONS
+	 *
+	 * [--apply]
+	 * : Actually move files. Without this flag the command only reports what
+	 *   it would do.
+	 *
+	 * [--verbose]
+	 * : List the ambiguous names with their candidate source directories.
+	 *
+	 * ## EXAMPLES
+	 *
+	 *     wp timber-kit migrate-image-cache
+	 *     wp timber-kit migrate-image-cache --apply
+	 *     wp timber-kit migrate-image-cache --verbose
+	 *
+	 * @param array<int, string>    $args       Positional args (unused).
+	 * @param array<string, string> $assoc_args Associative args.
+	 * @return void
+	 */
+	public function __invoke( $args, $assoc_args ) {
+		$apply   = isset( $assoc_args['apply'] );
+		$verbose = isset( $assoc_args['verbose'] );
+
+		$cache_dir = untrailingslashit( trailingslashit( WP_CONTENT_DIR ) . 'cache/image' );
+
+		$migrator = new ImageCacheMigrator( $cache_dir, $this->buildNameToDirs() );
+		$plan     = $migrator->plan();
+
+		$scanned = count( $plan['move'] ) + count( $plan['ambiguous'] ) + count( $plan['orphaned'] ) + count( $plan['conflict'] );
+
+		\WP_CLI::log( sprintf( 'scanned      : %d', $scanned ) );
+		\WP_CLI::log( sprintf( 'unambiguous  : %d  -> move', count( $plan['move'] ) ) );
+		\WP_CLI::log( sprintf( 'ambiguous    : %d  -> left in place', count( $plan['ambiguous'] ) ) );
+		\WP_CLI::log( sprintf( 'orphaned     : %d', count( $plan['orphaned'] ) ) );
+		\WP_CLI::log( sprintf( 'conflicts    : %d', count( $plan['conflict'] ) ) );
+
+		if ( $verbose && array() !== $plan['ambiguous'] ) {
+			\WP_CLI::log( '' );
+			foreach ( $plan['ambiguous'] as $relative => $dirs ) {
+				\WP_CLI::log( sprintf( '  %s: %s', $relative, implode( ', ', $dirs ) ) );
+			}
+		}
+
+		if ( ! $apply ) {
+			\WP_CLI::log( '(dry run -- nothing moved)' );
+			return;
+		}
+
+		$result = $migrator->apply( $plan );
+
+		\WP_CLI::success( sprintf( 'Moved %d derivatives (%d failed).', $result['moved'], count( $result['failed'] ) ) );
+
+		foreach ( $result['failed'] as $source ) {
+			\WP_CLI::warning( sprintf( 'Failed to move %s.', $source ) );
+		}
+	}
+
+	/**
+	 * Build the cache-name => source-directories map from `_wp_attached_file`.
+	 *
+	 * @return array<string, list<string>>
+	 */
+	private function buildNameToDirs(): array {
+		global $wpdb;
+
+		$rows = $wpdb->get_col( "SELECT meta_value FROM {$wpdb->postmeta} WHERE meta_key = '_wp_attached_file'" );
+
+		$name_to_dirs = array();
+
+		foreach ( $rows as $row ) {
+			if ( ! is_string( $row ) || '' === $row ) {
+				continue;
+			}
+
+			$name = sanitize_file_name( pathinfo( basename( $row ), PATHINFO_FILENAME ) );
+			$dir  = dirname( $row );
+			$dir  = '.' === $dir ? '' : $dir;
+
+			if ( ! isset( $name_to_dirs[ $name ] ) ) {
+				$name_to_dirs[ $name ] = array();
+			}
+
+			if ( ! in_array( $dir, $name_to_dirs[ $name ], true ) ) {
+				$name_to_dirs[ $name ][] = $dir;
+			}
+		}
+
+		return $name_to_dirs;
+	}
+}
diff --git a/src/ImageCacheMigrator.php b/src/ImageCacheMigrator.php
new file mode 100644
index 0000000..7d47393
--- /dev/null
+++ b/src/ImageCacheMigrator.php
@@ -0,0 +1,162 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Parisek\TimberKit;
+
+/**
+ * Moves existing resizer cache derivatives from the flat layout
+ * (`<size>/<name>.<fmt>`) into the source-path layout
+ * (`<size>/<source-relative-dir>/<name>.<fmt>`) — see
+ * `docs/adr/0007-resizer-source-path-cache-key.md`.
+ *
+ * The cache filename drops the source's own extension: a derivative is named
+ * `pathinfo( basename( $src ), PATHINFO_FILENAME )` plus the *target* format,
+ * so `hero.avif` in the cache is keyed by `hero`, not `hero.avif`. That is why
+ * `11.png` and `11.jpg` collide as surely as two `11.png` in different months
+ * do, and why the lookup map passed to the constructor is built the same way.
+ *
+ * A candidate name can map to more than one source directory (the collision
+ * this ADR exists to fix). Recovering which source a flat derivative actually
+ * came from is exactly what the old layout destroyed, so an ambiguous name is
+ * reported, never guessed.
+ */
+class ImageCacheMigrator {
+
+	/**
+	 * @param string                $cache_dir    Absolute path to the resizer
+	 *                                            cache root (holds the size
+	 *                                            directories directly).
+	 * @param array<string, list<string>> $name_to_dirs Cache name (source
+	 *                                            basename without extension,
+	 *                                            run through
+	 *                                            `sanitize_file_name()`)
+	 *                                            mapped to its distinct
+	 *                                            source directories.
+	 */
+	public function __construct(
+		private readonly string $cache_dir,
+		private readonly array $name_to_dirs
+	) {
+	}
+
+	/**
+	 * Plan the migration without touching the filesystem.
+	 *
+	 * `move` is keyed by absolute source paths because `apply()` calls
+	 * `rename()` on them directly. `ambiguous`, `orphaned` and `conflict` use
+	 * paths relative to the cache root instead, because they are printed to an
+	 * operator and a short relative path reads better than a long absolute
+	 * one — nothing downstream needs to `rename()` those.
+	 *
+	 * @return array{move: array<string,string>, ambiguous: array<string, list<string>>, orphaned: list<string>, conflict: list<string>}
+	 */
+	public function plan(): array {
+		$move      = array();
+		$ambiguous = array();
+		$orphaned  = array();
+		$conflict  = array();
+
+		foreach ( $this->candidates() as $relative => $absolute ) {
+			$size_dir = dirname( $relative );
+			$filename = basename( $relative );
+			$name     = pathinfo( $filename, PATHINFO_FILENAME );
+
+			$dirs = $this->name_to_dirs[ $name ] ?? array();
+
+			if ( array() === $dirs ) {
+				$orphaned[] = $relative;
+				continue;
+			}
+
+			if ( count( $dirs ) > 1 ) {
+				$ambiguous[ $relative ] = $dirs;
+				continue;
+			}
+
+			$target = $this->cache_dir . '/' . $size_dir . '/' . $dirs[0] . '/' . $filename;
+
+			if ( is_file( $target ) ) {
+				$conflict[] = $relative;
+				continue;
+			}
+
+			$move[ $absolute ] = $target;
+		}
+
+		return array(
+			'move'      => $move,
+			'ambiguous' => $ambiguous,
+			'orphaned'  => $orphaned,
+			'conflict'  => $conflict,
+		);
+	}
+
+	/**
+	 * Execute a plan produced by {@see plan()}. Never deletes, never
+	 * overwrites — the target directory is created and the file is `rename()`d
+	 * within the same filesystem, so the move is atomic and an interrupted run
+	 * leaves no partial file.
+	 *
+	 * @param array{move: array<string,string>, ambiguous: array<string, list<string>>, orphaned: list<string>, conflict: list<string>} $plan
+	 * @return array{moved: int, failed: list<string>}
+	 */
+	public function apply( array $plan ): array {
+		$moved  = 0;
+		$failed = array();
+
+		foreach ( $plan['move'] as $source => $target ) {
+			$target_dir = dirname( $target );
+
+			if ( ! is_dir( $target_dir ) && ! mkdir( $target_dir, 0777, true ) && ! is_dir( $target_dir ) ) {
+				$failed[] = $source;
+				continue;
+			}
+
+			if ( rename( $source, $target ) ) {
+				++$moved;
+			} else {
+				$failed[] = $source;
+			}
+		}
+
+		return array(
+			'moved'  => $moved,
+			'failed' => $failed,
+		);
+	}
+
+	/**
+	 * Files sitting directly inside a size directory (`<cache>/<size>/<file>`).
+	 * Anything deeper already carries a source-relative-dir segment and is
+	 * therefore already migrated, so it is not a candidate.
+	 *
+	 * @return array<string,string> Relative path (from `$cache_dir`) => absolute path.
+	 */
+	private function candidates(): array {
+		$found = array();
+
+		$size_dirs = glob( $this->cache_dir . '/*', GLOB_ONLYDIR );
+		if ( false === $size_dirs ) {
+			return $found;
+		}
+
+		foreach ( $size_dirs as $size_dir ) {
+			$files = glob( $size_dir . '/*' );
+			if ( false === $files ) {
+				continue;
+			}
+
+			foreach ( $files as $file ) {
+				if ( ! is_file( $file ) ) {
+					continue;
+				}
+
+				$relative           = ltrim( substr( $file, strlen( $this->cache_dir ) ), '/' );
+				$found[ $relative ] = $file;
+			}
+		}
+
+		return $found;
+	}
+}
diff --git a/src/StarterBase.php b/src/StarterBase.php
index 68b002e..f2d8c07 100644
--- a/src/StarterBase.php
+++ b/src/StarterBase.php
@@ -943,6 +943,7 @@ private function registerCliCommands(): void {
 		\WP_CLI::add_command( 'timber-kit acfml-sync-preferences', \Parisek\TimberKit\Cli\AcfmlSyncPreferencesCommand::class );
 		\WP_CLI::add_command( 'timber-kit wpml-cleanup-theme-domain', \Parisek\TimberKit\Cli\WpmlCleanupThemeDomainCommand::class );
 		\WP_CLI::add_command( 'timber-kit outage-screen', \Parisek\TimberKit\Cli\OutageScreenCommand::class );
+		\WP_CLI::add_command( 'timber-kit migrate-image-cache', \Parisek\TimberKit\Cli\MigrateImageCacheCommand::class );
 		// Registered regardless of $svg_dimensions: a sweep a human runs on purpose
 		// is opt-in by being typed, and the existing backlog needs fixing on
 		// projects that have not flipped the upload flag.
diff --git a/tests/Unit/ImageCacheMigrator/MigratePlanTest.php b/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
new file mode 100644
index 0000000..841213b
--- /dev/null
+++ b/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\ImageCacheMigrator;
+
+use Parisek\TimberKit\ImageCacheMigrator;
+use PHPUnit\Framework\TestCase;
+
+class MigratePlanTest extends TestCase {
+
+	private string $dir;
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->dir = sys_get_temp_dir() . '/tk-cache-' . bin2hex( random_bytes( 6 ) );
+		mkdir( $this->dir . '/900x0-center', 0777, true );
+	}
+
+	protected function tearDown(): void {
+		$it = new \RecursiveIteratorIterator(
+			new \RecursiveDirectoryIterator( $this->dir, \RecursiveDirectoryIterator::SKIP_DOTS ),
+			\RecursiveIteratorIterator::CHILD_FIRST
+		);
+		foreach ( $it as $f ) {
+			$f->isDir() ? rmdir( $f->getPathname() ) : unlink( $f->getPathname() );
+		}
+		rmdir( $this->dir );
+		parent::tearDown();
+	}
+
+	private function seed( string $relative ): string {
+		$path = $this->dir . '/' . $relative;
+		@mkdir( dirname( $path ), 0777, true );
+		file_put_contents( $path, 'x' );
+		return $path;
+	}
+
+	public function test_unambiguous_name_is_planned_for_a_move(): void {
+		$src = $this->seed( '900x0-center/hero.avif' );
+		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] ) )->plan();
+
+		$this->assertSame(
+			[ $src => $this->dir . '/900x0-center/2026/08/hero.avif' ],
+			$plan['move']
+		);
+		$this->assertSame( [], $plan['ambiguous'] );
+	}
+
+	public function test_ambiguous_name_is_reported_with_its_candidates(): void {
+		$this->seed( '900x0-center/11.avif' );
+		$plan = ( new ImageCacheMigrator( $this->dir, [ '11' => [ '2022/03', '2022/10' ] ] ) )->plan();
+
+		$this->assertSame( [], $plan['move'] );
+		$this->assertSame( [ '2022/03', '2022/10' ], $plan['ambiguous']['900x0-center/11.avif'] );
+	}
+
+	public function test_name_absent_from_the_database_is_reported_as_orphaned(): void {
+		$this->seed( '900x0-center/gone.avif' );
+		$plan = ( new ImageCacheMigrator( $this->dir, [] ) )->plan();
+
+		$this->assertSame( [], $plan['move'] );
+		$this->assertSame( [ '900x0-center/gone.avif' ], $plan['orphaned'] );
+	}
+
+	public function test_existing_target_is_reported_as_a_conflict_not_overwritten(): void {
+		$this->seed( '900x0-center/hero.avif' );
+		$this->seed( '900x0-center/2026/08/hero.avif' );
+		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] ) )->plan();
+
+		$this->assertSame( [], $plan['move'] );
+		$this->assertSame( [ '900x0-center/hero.avif' ], $plan['conflict'] );
+	}
+
+	/** A file already in the new layout is not a candidate. */
+	public function test_already_migrated_file_is_left_alone(): void {
+		$this->seed( '900x0-center/2026/08/hero.avif' );
+		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] ) )->plan();
+
+		$this->assertSame( [], $plan['move'] );
+		$this->assertSame( [], $plan['orphaned'] );
+	}
+
+	public function test_apply_moves_the_file_and_a_second_run_finds_nothing(): void {
+		$src = $this->seed( '900x0-center/hero.avif' );
+		$migrator = new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] );
+
+		$result = $migrator->apply( $migrator->plan() );
+
+		$this->assertSame( 1, $result['moved'] );
+		$this->assertSame( [], $result['failed'] );
+		$this->assertFileDoesNotExist( $src );
+		$this->assertFileExists( $this->dir . '/900x0-center/2026/08/hero.avif' );
+
+		$this->assertSame( [], ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] ) )->plan()['move'] );
+	}
+}

From 1925a6aab21848648e29775a79ef318a5fc5d57a Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Wed, 26 Aug 2026 23:22:11 +0200
Subject: [PATCH 06/16] fix(cli): re-check the migrate-image-cache target
 before rename and guard source dirs

---
 src/Cli/MigrateImageCacheCommand.php          | 65 +++++++++++++++++--
 src/ImageCacheMigrator.php                    | 11 ++++
 .../Cli/MigrateImageCacheCommandGuardTest.php | 57 ++++++++++++++++
 .../ImageCacheMigrator/MigratePlanTest.php    | 23 +++++++
 4 files changed, 151 insertions(+), 5 deletions(-)
 create mode 100644 tests/Unit/Cli/MigrateImageCacheCommandGuardTest.php

diff --git a/src/Cli/MigrateImageCacheCommand.php b/src/Cli/MigrateImageCacheCommand.php
index 50b2e6e..e19327d 100644
--- a/src/Cli/MigrateImageCacheCommand.php
+++ b/src/Cli/MigrateImageCacheCommand.php
@@ -81,6 +81,14 @@ public function __invoke( $args, $assoc_args ) {
 	/**
 	 * Build the cache-name => source-directories map from `_wp_attached_file`.
 	 *
+	 * Every directory goes through {@see guardSourceDir()} first. Skipping a
+	 * directory that fails it (rather than mapping it anyway) matters because
+	 * the flag-enabled `Resizer` applies the identical guard at render time
+	 * (`Resizer::sourcePathSegment()`): a directory it rejects never gets a
+	 * cache subdirectory there either, so the derivative stays at the flat
+	 * key. Mapping it here would move the file into a nested path nothing
+	 * ever looks up again.
+	 *
 	 * @return array<string, list<string>>
 	 */
 	private function buildNameToDirs(): array {
@@ -95,19 +103,66 @@ private function buildNameToDirs(): array {
 				continue;
 			}
 
-			$name = sanitize_file_name( pathinfo( basename( $row ), PATHINFO_FILENAME ) );
-			$dir  = dirname( $row );
-			$dir  = '.' === $dir ? '' : $dir;
+			$name        = sanitize_file_name( pathinfo( basename( $row ), PATHINFO_FILENAME ) );
+			$source_dir  = dirname( $row );
+			$guarded_dir = self::guardSourceDir( $source_dir );
+
+			// An upload at the uploads root (dirname() === '.') legitimately
+			// guards to '' — that is still a valid, flat mapping, so it must
+			// not be conflated with a directory the guard rejected.
+			if ( '' === $guarded_dir && '.' !== $source_dir ) {
+				continue;
+			}
 
 			if ( ! isset( $name_to_dirs[ $name ] ) ) {
 				$name_to_dirs[ $name ] = array();
 			}
 
-			if ( ! in_array( $dir, $name_to_dirs[ $name ], true ) ) {
-				$name_to_dirs[ $name ][] = $dir;
+			if ( ! in_array( $guarded_dir, $name_to_dirs[ $name ], true ) ) {
+				$name_to_dirs[ $name ][] = $guarded_dir;
 			}
 		}
 
 		return $name_to_dirs;
 	}
+
+	/**
+	 * Mirror (not reuse — `Resizer::sourcePathSegment()` is private and takes
+	 * a URL, not a relative path) the per-component guard the runtime applies
+	 * before it will place a derivative under a source directory: every
+	 * component must survive `sanitize_file_name()` unchanged and be neither
+	 * empty nor `.`/`..`. One failing component voids the whole directory
+	 * rather than being silently dropped or repaired — dropping just that
+	 * component would quietly point the migration at a different directory
+	 * than the one the upload is actually in.
+	 *
+	 * Public and static because, unlike the rest of this class, it is a pure
+	 * function of its input — see the class docblock on why the rest isn't
+	 * unit-tested.
+	 *
+	 * @param string $dir Relative directory, e.g. from `dirname( $attached_file )`.
+	 * @return string The same directory, or '' when any component fails the guard.
+	 */
+	public static function guardSourceDir( string $dir ): string {
+		if ( '' === $dir || '.' === $dir ) {
+			return '';
+		}
+
+		$parts = array();
+
+		foreach ( explode( '/', $dir ) as $part ) {
+			if ( '' === $part || '.' === $part || '..' === $part ) {
+				return '';
+			}
+
+			$clean = sanitize_file_name( $part );
+			if ( '' === $clean || $clean !== $part ) {
+				return '';
+			}
+
+			$parts[] = $clean;
+		}
+
+		return implode( '/', $parts );
+	}
 }
diff --git a/src/ImageCacheMigrator.php b/src/ImageCacheMigrator.php
index 7d47393..b70bcc9 100644
--- a/src/ImageCacheMigrator.php
+++ b/src/ImageCacheMigrator.php
@@ -106,6 +106,17 @@ public function apply( array $plan ): array {
 		$failed = array();
 
 		foreach ( $plan['move'] as $source => $target ) {
+			// plan() only snapshots the filesystem; by the time this loop
+			// reaches an entry, another process (a second invocation, a file
+			// dropped by hand) may have created the target since. rename()
+			// silently replaces an existing destination on POSIX, so the
+			// "never overwrites" rule needs this re-check right here, not
+			// just in plan().
+			if ( is_file( $target ) ) {
+				$failed[] = $source;
+				continue;
+			}
+
 			$target_dir = dirname( $target );
 
 			if ( ! is_dir( $target_dir ) && ! mkdir( $target_dir, 0777, true ) && ! is_dir( $target_dir ) ) {
diff --git a/tests/Unit/Cli/MigrateImageCacheCommandGuardTest.php b/tests/Unit/Cli/MigrateImageCacheCommandGuardTest.php
new file mode 100644
index 0000000..526dae2
--- /dev/null
+++ b/tests/Unit/Cli/MigrateImageCacheCommandGuardTest.php
@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Cli;
+
+use Brain\Monkey;
+use Brain\Monkey\Functions;
+use Parisek\TimberKit\Cli\MigrateImageCacheCommand;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * `guardSourceDir()` is the one piece of `MigrateImageCacheCommand` that is a
+ * pure function of its input (no `$wpdb`, no `WP_CLI`), so — unlike the rest
+ * of the class, which is WP_CLI I/O and deliberately not unit-tested — it is
+ * tested directly. It must classify a directory exactly the way
+ * `Resizer::sourcePathSegment()` does per path component, or the migrator can
+ * move a derivative into a subdirectory the flag-enabled `Resizer` will never
+ * look in.
+ */
+class MigrateImageCacheCommandGuardTest extends TestCase {
+
+	protected function setUp(): void {
+		parent::setUp();
+		Monkey\setUp();
+
+		// Same stub shape as Resizer's own SourcePathSegmentTest: keep
+		// A-Za-z0-9._-, strip the rest.
+		Functions\when( 'sanitize_file_name' )->alias( function ( $name ) {
+			return preg_replace( '/[^A-Za-z0-9._-]/', '', (string) $name );
+		} );
+	}
+
+	protected function tearDown(): void {
+		Monkey\tearDown();
+		parent::tearDown();
+	}
+
+	public static function directories(): array {
+		return [
+			'plain year/month' => [ '2026/08', '2026/08' ],
+			'deeper custom structure' => [ 'sites/3/2026/08', 'sites/3/2026/08' ],
+			'root upload (no directory)' => [ '', '' ],
+			'dot from dirname()' => [ '.', '' ],
+			'traversal component' => [ '2026/../evil', '' ],
+			'dot component' => [ '2026/./08', '' ],
+			'empty component from a double slash' => [ '2026//08', '' ],
+			'component sanitize_file_name() would alter' => [ '2026/aug ust', '' ],
+		];
+	}
+
+	#[DataProvider( 'directories' )]
+	public function test_guard_source_dir( string $dir, string $expected ): void {
+		$this->assertSame( $expected, MigrateImageCacheCommand::guardSourceDir( $dir ) );
+	}
+}
diff --git a/tests/Unit/ImageCacheMigrator/MigratePlanTest.php b/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
index 841213b..52ea549 100644
--- a/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
+++ b/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
@@ -94,4 +94,27 @@ public function test_apply_moves_the_file_and_a_second_run_finds_nothing(): void
 
 		$this->assertSame( [], ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] ) )->plan()['move'] );
 	}
+
+	/**
+	 * A target can appear between `plan()` snapshotting the filesystem and
+	 * `apply()` reaching that entry — another invocation, a manually placed
+	 * file, anything. `rename()` silently replaces an existing destination on
+	 * POSIX, so `apply()` must re-check immediately before calling it, not
+	 * trust the snapshot `plan()` took.
+	 */
+	public function test_apply_does_not_overwrite_a_target_that_appeared_after_planning(): void {
+		$src = $this->seed( '900x0-center/hero.avif' );
+		$migrator = new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] );
+
+		$plan = $migrator->plan();
+		$target = $this->seed( '900x0-center/2026/08/hero.avif' );
+		file_put_contents( $target, 'pre-existing' );
+
+		$result = $migrator->apply( $plan );
+
+		$this->assertSame( 0, $result['moved'] );
+		$this->assertSame( [ $src ], $result['failed'] );
+		$this->assertFileExists( $src );
+		$this->assertSame( 'pre-existing', file_get_contents( $target ) );
+	}
 }

From 0b246e92e13fc6379c668531afaaf9e2dd1e7fb1 Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Wed, 26 Aug 2026 23:29:32 +0200
Subject: [PATCH 07/16] fix(media): address cached derivatives instead of
 scanning for them

---
 src/StarterBase.php                           | 89 ++++++++++++++++---
 .../StarterBase/CleanupCachedImagesTest.php   | 27 ++++++
 2 files changed, 103 insertions(+), 13 deletions(-)

diff --git a/src/StarterBase.php b/src/StarterBase.php
index f2d8c07..e67bb11 100644
--- a/src/StarterBase.php
+++ b/src/StarterBase.php
@@ -3921,7 +3921,42 @@ public function cleanup_cached_images( $attachment_id ) {
 			return;
 		}
 
-		// Scan cache directory for matching files (including nested directories)
+		if ( $this->resizer_source_path_in_cache_key ) {
+			// Layout is <size>/<source-upload-dir>/<name>.<fmt>. That source
+			// directory and name are the same segments `_wp_attached_file`
+			// carries, so the derivative paths are derivable directly — no
+			// scan, and no risk of matching a different upload's basename.
+			$files_to_delete = $this->cached_derivative_paths_by_source_path( $cache_dir, $attachment_id );
+		} else {
+			$files_to_delete = $this->cached_derivative_paths_by_basename_scan( $cache_dir, $basename );
+		}
+
+		if ( ! empty( $files_to_delete ) ) {
+			// Initialize the WordPress filesystem
+			if ( ! function_exists( 'WP_Filesystem' ) ) {
+				require_once ABSPATH . 'wp-admin/includes/file.php';
+			}
+			global $wp_filesystem;
+			\WP_Filesystem();
+
+			// Delete the matched files
+			foreach ( $files_to_delete as $file_to_delete ) {
+				if ( $wp_filesystem->exists( $file_to_delete ) ) {
+					$wp_filesystem->delete( $file_to_delete );
+				}
+			}
+		}
+	}
+
+	/**
+	 * Locate cached derivatives by scanning the whole cache tree for a matching
+	 * basename — the flag-off layout, where the source path isn't in the key.
+	 *
+	 * @param string $cache_dir Absolute path to `wp-content/cache/image`.
+	 * @param string $basename  Attachment filename without its extension.
+	 * @return list<string> Absolute paths of derivatives to delete.
+	 */
+	private function cached_derivative_paths_by_basename_scan( $cache_dir, $basename ) {
 		$files_to_delete = [];
 
 		$directory_iterator = new \RecursiveIteratorIterator(
@@ -3948,21 +3983,49 @@ public function cleanup_cached_images( $attachment_id ) {
 			}
 		}
 
-		if ( ! empty( $files_to_delete ) ) {
-			// Initialize the WordPress filesystem
-			if ( ! function_exists( 'WP_Filesystem' ) ) {
-				require_once ABSPATH . 'wp-admin/includes/file.php';
-			}
-			global $wp_filesystem;
-			\WP_Filesystem();
+		return $files_to_delete;
+	}
 
-			// Delete the matched files
-			foreach ( $files_to_delete as $file_to_delete ) {
-				if ( $wp_filesystem->exists( $file_to_delete ) ) {
-					$wp_filesystem->delete( $file_to_delete );
-				}
+	/**
+	 * Locate cached derivatives directly — the flag-on layout, where the cache
+	 * key is `<size>/<source-upload-dir>/<name>.<fmt>`. `<source-upload-dir>/
+	 * <name>` is `_wp_attached_file` without its extension, so every derivative
+	 * lives at a predictable path under each size directory. No scan, and no
+	 * risk of touching a different upload's derivatives.
+	 *
+	 * Never deletes the size directory or the source subdirectory themselves,
+	 * even once emptied — another attachment's derivative may land there next.
+	 *
+	 * @param string $cache_dir     Absolute path to `wp-content/cache/image`.
+	 * @param int    $attachment_id The attachment being deleted.
+	 * @return list<string> Absolute paths of derivatives to delete.
+	 */
+	private function cached_derivative_paths_by_source_path( $cache_dir, $attachment_id ) {
+		$relative_path = get_post_meta( (int) $attachment_id, '_wp_attached_file', true );
+
+		if ( ! is_string( $relative_path ) || '' === $relative_path ) {
+			return [];
+		}
+
+		$source_dir = trim( dirname( $relative_path ), '.' );
+		$name = pathinfo( $relative_path, PATHINFO_FILENAME );
+
+		if ( '' === $name ) {
+			return [];
+		}
+
+		$files_to_delete = [];
+
+		foreach ( glob( $cache_dir . '/*', GLOB_ONLYDIR ) ?: [] as $size_dir ) {
+			$source_path = '' === $source_dir ? $size_dir : $size_dir . '/' . $source_dir;
+			$matches = glob( $source_path . '/' . $name . '.*' );
+
+			if ( $matches ) {
+				array_push( $files_to_delete, ...$matches );
 			}
 		}
+
+		return $files_to_delete;
 	}
 
 	/**
diff --git a/tests/Unit/StarterBase/CleanupCachedImagesTest.php b/tests/Unit/StarterBase/CleanupCachedImagesTest.php
index 7a5b0b9..d6a2f11 100644
--- a/tests/Unit/StarterBase/CleanupCachedImagesTest.php
+++ b/tests/Unit/StarterBase/CleanupCachedImagesTest.php
@@ -210,6 +210,33 @@ public function test_asks_the_database_the_question_it_claims_to_ask(): void {
 		);
 	}
 
+	/** Same override the flag's own registration test uses. */
+	private function enableSourcePathCacheKey(): void {
+		( new \ReflectionClass( \Parisek\TimberKit\StarterBase::class ) )
+			->getProperty( 'resizer_source_path_in_cache_key' )
+			->setValue( $this->base, true );
+	}
+
+	public function test_with_the_flag_on_only_the_matching_source_directory_is_deleted(): void {
+		mkdir( $this->cache_dir . '/900x0-center/2022/03', 0777, true );
+		mkdir( $this->cache_dir . '/900x0-center/2022/10', 0777, true );
+		$this->created[] = $this->cache_dir . '/900x0-center/2022/03';
+		$this->created[] = $this->cache_dir . '/900x0-center/2022/10';
+		$this->seedFile( $this->cache_dir . '/900x0-center/2022/03/11.avif' );
+		$this->seedFile( $this->cache_dir . '/900x0-center/2022/10/11.avif' );
+
+		$this->stubAttachment( 4711, '2022/03/11.png', siblings: 0 );
+		$this->enableSourcePathCacheKey();
+
+		$this->base->cleanup_cached_images( 4711 );
+
+		$this->assertFileDoesNotExist( $this->cache_dir . '/900x0-center/2022/03/11.avif' );
+		$this->assertFileExists(
+			$this->cache_dir . '/900x0-center/2022/10/11.avif',
+			'a different upload that happens to share a name must survive'
+		);
+	}
+
 	public function test_keeps_derivatives_when_the_sibling_count_is_unavailable(): void {
 		$this->seedDerivatives();
 		Functions\when( 'get_attached_file' )->justReturn( '/var/www/wp-content/uploads/2026/08/homepage-hero-desktop.webp' );

From cd4f7c3e16de8cbff1f8e004cd29b75f3210e18c Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Wed, 26 Aug 2026 23:41:39 +0200
Subject: [PATCH 08/16] fix(media): address cached derivatives instead of
 scanning for them

---
 src/StarterBase.php                           | 65 ++++++++++++++-
 .../StarterBase/CleanupCachedImagesTest.php   | 79 +++++++++++++++++++
 2 files changed, 140 insertions(+), 4 deletions(-)

diff --git a/src/StarterBase.php b/src/StarterBase.php
index e67bb11..86fe9a6 100644
--- a/src/StarterBase.php
+++ b/src/StarterBase.php
@@ -4007,27 +4007,84 @@ private function cached_derivative_paths_by_source_path( $cache_dir, $attachment
 			return [];
 		}
 
-		$source_dir = trim( dirname( $relative_path ), '.' );
-		$name = pathinfo( $relative_path, PATHINFO_FILENAME );
+		// The writer (Resizer.php) sanitizes the name before it ever reaches
+		// disk. Using the raw value here would both miss the writer's own
+		// sanitized file (an accent or space stripped at write time never
+		// matches back) and, worse, hand a bracket or asterisk straight to
+		// glob() as a live pattern instead of a literal filename — matching
+		// whatever else happens to sit in that character class or wildcard.
+		// A name that sanitizes to nothing can't be resolved either way.
+		$name = sanitize_file_name( pathinfo( $relative_path, PATHINFO_FILENAME ) );
 
 		if ( '' === $name ) {
 			return [];
 		}
 
+		// Mirrors (does not call — StarterBase and MigrateImageCacheCommand
+		// stay decoupled) MigrateImageCacheCommand::guardSourceDir(), which
+		// itself mirrors Resizer::sourcePathSegment(): a directory is only
+		// used whole, component-by-component sanitized and never `.`/`..`.
+		// The writer falls back to the flat root when its own guard rejects
+		// a component, so collapsing to the flat root here — rather than
+		// giving up — reaches the same file the writer actually created.
+		$source_dir = $this->guarded_cached_derivative_source_dir( dirname( $relative_path ) );
+
 		$files_to_delete = [];
 
 		foreach ( glob( $cache_dir . '/*', GLOB_ONLYDIR ) ?: [] as $size_dir ) {
 			$source_path = '' === $source_dir ? $size_dir : $size_dir . '/' . $source_dir;
 			$matches = glob( $source_path . '/' . $name . '.*' );
 
-			if ( $matches ) {
-				array_push( $files_to_delete, ...$matches );
+			foreach ( $matches ?: [] as $match ) {
+				// A stray directory (e.g. a leftover `.bak` folder) can match
+				// the glob too; deleting it needs a recursive flag this loop
+				// doesn't have, so skip it rather than hand it to delete().
+				if ( is_file( $match ) ) {
+					$files_to_delete[] = $match;
+				}
 			}
 		}
 
 		return $files_to_delete;
 	}
 
+	/**
+	 * Per-component guard for a source-upload directory, mirroring
+	 * `MigrateImageCacheCommand::guardSourceDir()` (itself a mirror of
+	 * `Resizer::sourcePathSegment()`): every component must survive
+	 * `sanitize_file_name()` unchanged and be neither empty nor `.`/`..`.
+	 * One failing component collapses the whole directory to the flat root
+	 * rather than being silently dropped or repaired — dropping just that
+	 * component would point the delete at a different directory than the one
+	 * the upload is actually in.
+	 *
+	 * @param string $dir Relative directory, e.g. from `dirname( $relative_path )`.
+	 * @return string The same directory, or '' (the flat root) when any component fails the guard.
+	 */
+	private function guarded_cached_derivative_source_dir( $dir ) {
+		if ( '' === $dir || '.' === $dir ) {
+			return '';
+		}
+
+		$parts = [];
+
+		foreach ( explode( '/', $dir ) as $part ) {
+			if ( '' === $part || '.' === $part || '..' === $part ) {
+				return '';
+			}
+
+			$clean = sanitize_file_name( $part );
+
+			if ( '' === $clean || $clean !== $part ) {
+				return '';
+			}
+
+			$parts[] = $clean;
+		}
+
+		return implode( '/', $parts );
+	}
+
 	/**
 	 * Whether an attachment other than this one still points at the same file.
 	 *
diff --git a/tests/Unit/StarterBase/CleanupCachedImagesTest.php b/tests/Unit/StarterBase/CleanupCachedImagesTest.php
index d6a2f11..91d2bf8 100644
--- a/tests/Unit/StarterBase/CleanupCachedImagesTest.php
+++ b/tests/Unit/StarterBase/CleanupCachedImagesTest.php
@@ -40,6 +40,15 @@ protected function setUp(): void {
 		$this->makeDir( $this->cache_dir . '/1439x0-center' );
 
 		$this->stubFilesystem();
+
+		// Same stub shape as guardSourceDir()'s own test and Resizer's
+		// SourcePathSegmentTest: keep A-Za-z0-9._-, strip the rest. This is
+		// the function the writer (Resizer.php) sanitizes names through, so
+		// stubbing it here lets the flag-on tests exercise the same
+		// name-collapsing rule the real cache key was written with.
+		Functions\when( 'sanitize_file_name' )->alias( function ( $name ) {
+			return preg_replace( '/[^A-Za-z0-9._-]/', '', (string) $name );
+		} );
 	}
 
 	protected function tearDown(): void {
@@ -237,6 +246,76 @@ public function test_with_the_flag_on_only_the_matching_source_directory_is_dele
 		);
 	}
 
+	/**
+	 * A raw (unsanitized) name used directly as a glob pattern turns a bracket
+	 * expression into a live character class. `img[0-9]` is a legitimate
+	 * (if odd) filename component that survives to `_wp_attached_file`
+	 * unsanitized in scenarios the upload sanitizer never saw — a migration
+	 * script, an offloaded-media plugin writing meta directly. Sanitizing it
+	 * the way the writer (`Resizer.php`) does collapses it to `img0-9`, the
+	 * literal name the real derivative was written under; skipping that step
+	 * makes the delete pattern `img[0-9].*`, which glob reads as "img" plus
+	 * exactly one digit — matching an unrelated upload's `img5.avif` and
+	 * missing the target's own `img0-9.avif` entirely.
+	 */
+	public function test_with_the_flag_on_a_glob_metacharacter_in_the_name_does_not_reach_an_unrelated_derivative(): void {
+		mkdir( $this->cache_dir . '/900x0-center/2022/03', 0777, true );
+		$this->created[] = $this->cache_dir . '/900x0-center/2022/03';
+		$this->seedFile( $this->cache_dir . '/900x0-center/2022/03/img0-9.avif' );
+		$this->seedFile( $this->cache_dir . '/900x0-center/2022/03/img5.avif' );
+
+		$this->stubAttachment( 4711, '2022/03/img[0-9].png', siblings: 0 );
+		$this->enableSourcePathCacheKey();
+
+		$this->base->cleanup_cached_images( 4711 );
+
+		$this->assertFileDoesNotExist(
+			$this->cache_dir . '/900x0-center/2022/03/img0-9.avif',
+			'the target attachment\'s own (sanitized) derivative must still be found and deleted'
+		);
+		$this->assertFileExists(
+			$this->cache_dir . '/900x0-center/2022/03/img5.avif',
+			'an unrelated upload must not be swept up by an unsanitized glob pattern'
+		);
+	}
+
+	/**
+	 * `_wp_attached_file` is database content. A corrupted or plugin-written
+	 * value can carry a `..` segment; unguarded, that walks the glob outside
+	 * both the source directory and the cache root. Mirrors
+	 * `MigrateImageCacheCommand::guardSourceDir()`, which collapses any
+	 * invalid directory (including one with a traversal component) to the
+	 * flat root — matching the writer, which does the same when its own
+	 * mirrored guard (`Resizer::sourcePathSegment()`) rejects a component.
+	 */
+	public function test_with_the_flag_on_a_traversal_segment_in_the_directory_is_treated_as_the_flat_root(): void {
+		// The target's real derivative, at the flat root the guard falls back to.
+		$this->seedFile( $this->cache_dir . '/900x0-center/11.avif' );
+
+		// A file well outside the cache tree — a `..` component joined onto
+		// a size directory and walked by the filesystem can reach anything
+		// under WP_CONTENT_DIR, not just a sibling inside the cache. Placed
+		// outside `$cache_dir` on purpose, so it can never be reached by
+		// enumerating `$cache_dir`'s own subdirectories either.
+		$outside_dir = dirname( $this->cache_dir ) . '/decoy';
+		$this->makeDir( $outside_dir );
+		$this->seedFile( $outside_dir . '/11.avif' );
+
+		$this->stubAttachment( 4711, '../decoy/11.png', siblings: 0 );
+		$this->enableSourcePathCacheKey();
+
+		$this->base->cleanup_cached_images( 4711 );
+
+		$this->assertFileExists(
+			$outside_dir . '/11.avif',
+			'a traversal segment must never let the delete walk outside the cache tree'
+		);
+		$this->assertFileDoesNotExist(
+			$this->cache_dir . '/900x0-center/11.avif',
+			'the guard collapses the whole invalid directory to the flat root, matching the writer\'s own fallback'
+		);
+	}
+
 	public function test_keeps_derivatives_when_the_sibling_count_is_unavailable(): void {
 		$this->seedDerivatives();
 		Functions\when( 'get_attached_file' )->justReturn( '/var/www/wp-content/uploads/2026/08/homepage-hero-desktop.webp' );

From 6fd148d950167a72b2b8819de164534e6e389721 Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Wed, 26 Aug 2026 23:46:03 +0200
Subject: [PATCH 09/16] docs(changelog): record the resizer source-path cache
 key

---
 CHANGELOG.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5347212..8c082e0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+### Added
+
+- `StarterBase::$resizer_source_path_in_cache_key` (default `false`) puts the
+  source image's upload directory in the resizer cache key, so two uploads that
+  share a name stop sharing one cached derivative. Without it the derivative is
+  named for the source alone, so `2022/03/11.png` and `2022/10/11.png` — and
+  `11.png` and `11.jpg`, because the extension is dropped too — occupy one path,
+  and whichever renders first decides what the others show. Measured on a
+  five-language production site: 496 names map to more than one source file.
+
+  Enabling it relocates every derivative whose source is below a year/month
+  directory; `wp timber-kit migrate-image-cache` (dry-run by default) moves the
+  existing cache into the new shape rather than re-encoding it. Derivatives whose
+  name maps to more than one source cannot be placed — recovering that
+  association is exactly what the flat layout destroyed — so they are reported
+  and left alone, and re-encoded on first view. A site with year/month folders
+  switched off gets byte-identical paths and needs no migration.
+
+  With the flag on, `cleanup_cached_images()` addresses derivatives by path
+  instead of matching basenames across the tree, so deleting an attachment can
+  no longer reach another upload's images.
+
+  Decision and alternatives: `docs/adr/0007-resizer-source-path-cache-key.md`.
+
 ### Fixed
 
 - `StarterBase::cleanup_cached_images()` deleted resizer derivatives that other

From fa2c052255405a63bca1ba1ce400868e9012e813 Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Wed, 26 Aug 2026 23:58:19 +0200
Subject: [PATCH 10/16] fix(image-cache-migrator): stop dropping guard-rejected
 directories and misreporting root uploads as conflicts

buildNameToDirs() silently dropped an attachment whose upload directory
failed guardSourceDir(), instead of folding it into the flat-key ''
candidate the way a genuine root upload does. A same-named clean
attachment then looked unambiguous and plan() moved the wrong
attachment's derivative into it.

plan() also built a target path from dirs[0] even when it was '' (a
root upload), which collapses via the double slash to the source file
itself: is_file() was always true, so every root-upload derivative was
reported as a conflict with itself. plan() now recognises dirs[0] === ''
as already in its final location and reports it in a new
already_in_place bucket instead.

MigrateImageCacheCommand's summary output and ImageCacheMigrator::apply()'s
docblock type were updated to match the new bucket.
---
 src/Cli/MigrateImageCacheCommand.php          |  46 ++++---
 src/ImageCacheMigrator.php                    |  44 ++++---
 ...teImageCacheCommandBuildNameToDirsTest.php | 117 ++++++++++++++++++
 .../ImageCacheMigrator/MigratePlanTest.php    |  19 +++
 4 files changed, 193 insertions(+), 33 deletions(-)
 create mode 100644 tests/Unit/Cli/MigrateImageCacheCommandBuildNameToDirsTest.php

diff --git a/src/Cli/MigrateImageCacheCommand.php b/src/Cli/MigrateImageCacheCommand.php
index e19327d..16c39ef 100644
--- a/src/Cli/MigrateImageCacheCommand.php
+++ b/src/Cli/MigrateImageCacheCommand.php
@@ -49,13 +49,15 @@ public function __invoke( $args, $assoc_args ) {
 		$migrator = new ImageCacheMigrator( $cache_dir, $this->buildNameToDirs() );
 		$plan     = $migrator->plan();
 
-		$scanned = count( $plan['move'] ) + count( $plan['ambiguous'] ) + count( $plan['orphaned'] ) + count( $plan['conflict'] );
+		$scanned = count( $plan['move'] ) + count( $plan['ambiguous'] ) + count( $plan['orphaned'] )
+			+ count( $plan['conflict'] ) + count( $plan['already_in_place'] );
 
-		\WP_CLI::log( sprintf( 'scanned      : %d', $scanned ) );
-		\WP_CLI::log( sprintf( 'unambiguous  : %d  -> move', count( $plan['move'] ) ) );
-		\WP_CLI::log( sprintf( 'ambiguous    : %d  -> left in place', count( $plan['ambiguous'] ) ) );
-		\WP_CLI::log( sprintf( 'orphaned     : %d', count( $plan['orphaned'] ) ) );
-		\WP_CLI::log( sprintf( 'conflicts    : %d', count( $plan['conflict'] ) ) );
+		\WP_CLI::log( sprintf( 'scanned          : %d', $scanned ) );
+		\WP_CLI::log( sprintf( 'unambiguous      : %d  -> move', count( $plan['move'] ) ) );
+		\WP_CLI::log( sprintf( 'ambiguous        : %d  -> left in place', count( $plan['ambiguous'] ) ) );
+		\WP_CLI::log( sprintf( 'orphaned         : %d', count( $plan['orphaned'] ) ) );
+		\WP_CLI::log( sprintf( 'conflicts        : %d', count( $plan['conflict'] ) ) );
+		\WP_CLI::log( sprintf( 'already in place : %d  -> root uploads, nothing to move', count( $plan['already_in_place'] ) ) );
 
 		if ( $verbose && array() !== $plan['ambiguous'] ) {
 			\WP_CLI::log( '' );
@@ -81,13 +83,15 @@ public function __invoke( $args, $assoc_args ) {
 	/**
 	 * Build the cache-name => source-directories map from `_wp_attached_file`.
 	 *
-	 * Every directory goes through {@see guardSourceDir()} first. Skipping a
-	 * directory that fails it (rather than mapping it anyway) matters because
-	 * the flag-enabled `Resizer` applies the identical guard at render time
-	 * (`Resizer::sourcePathSegment()`): a directory it rejects never gets a
-	 * cache subdirectory there either, so the derivative stays at the flat
-	 * key. Mapping it here would move the file into a nested path nothing
-	 * ever looks up again.
+	 * Every directory goes through {@see guardSourceDir()} first. A directory
+	 * it rejects contributes '' to the name's candidate list -- the same
+	 * value a genuine root upload contributes -- rather than being dropped.
+	 * Both cases mean the same thing to the flag-enabled `Resizer`
+	 * (`Resizer::sourcePathSegment()`): the derivative stays at the flat
+	 * cache key. Dropping a rejected attachment instead would erase it from
+	 * the map entirely, so a real collision at that flat key -- another
+	 * attachment sharing the basename -- would look unambiguous and move a
+	 * derivative that in fact belongs to the dropped attachment.
 	 *
 	 * @return array<string, list<string>>
 	 */
@@ -107,12 +111,12 @@ private function buildNameToDirs(): array {
 			$source_dir  = dirname( $row );
 			$guarded_dir = self::guardSourceDir( $source_dir );
 
-			// An upload at the uploads root (dirname() === '.') legitimately
-			// guards to '' — that is still a valid, flat mapping, so it must
-			// not be conflated with a directory the guard rejected.
-			if ( '' === $guarded_dir && '.' !== $source_dir ) {
-				continue;
-			}
+			// guardSourceDir() returns '' both for a genuine root upload
+			// (dirname() === '.') and for a directory it rejects. Both cases
+			// contribute '' here rather than one of them being dropped: the
+			// property this map exists to detect is "does the runtime keep
+			// this derivative at the flat key", and a rejected directory has
+			// that property exactly as much as a root upload does.
 
 			if ( ! isset( $name_to_dirs[ $name ] ) ) {
 				$name_to_dirs[ $name ] = array();
@@ -148,6 +152,10 @@ public static function guardSourceDir( string $dir ): string {
 			return '';
 		}
 
+		// No backslash normalization here, unlike Resizer::sourcePathSegment()
+		// (which reads a URL): this reads dirname() of `_wp_attached_file`,
+		// a database value WordPress always stores with forward slashes, so
+		// a backslash cannot occur in this input domain.
 		$parts = array();
 
 		foreach ( explode( '/', $dir ) as $part ) {
diff --git a/src/ImageCacheMigrator.php b/src/ImageCacheMigrator.php
index b70bcc9..d16c73f 100644
--- a/src/ImageCacheMigrator.php
+++ b/src/ImageCacheMigrator.php
@@ -44,18 +44,20 @@ public function __construct(
 	 * Plan the migration without touching the filesystem.
 	 *
 	 * `move` is keyed by absolute source paths because `apply()` calls
-	 * `rename()` on them directly. `ambiguous`, `orphaned` and `conflict` use
-	 * paths relative to the cache root instead, because they are printed to an
-	 * operator and a short relative path reads better than a long absolute
-	 * one — nothing downstream needs to `rename()` those.
+	 * `rename()` on them directly. `ambiguous`, `orphaned`, `conflict` and
+	 * `already_in_place` use paths relative to the cache root instead,
+	 * because they are printed to an operator and a short relative path
+	 * reads better than a long absolute one — nothing downstream needs to
+	 * `rename()` those.
 	 *
-	 * @return array{move: array<string,string>, ambiguous: array<string, list<string>>, orphaned: list<string>, conflict: list<string>}
+	 * @return array{move: array<string,string>, ambiguous: array<string, list<string>>, orphaned: list<string>, conflict: list<string>, already_in_place: list<string>}
 	 */
 	public function plan(): array {
-		$move      = array();
-		$ambiguous = array();
-		$orphaned  = array();
-		$conflict  = array();
+		$move             = array();
+		$ambiguous        = array();
+		$orphaned         = array();
+		$conflict         = array();
+		$already_in_place = array();
 
 		foreach ( $this->candidates() as $relative => $absolute ) {
 			$size_dir = dirname( $relative );
@@ -74,6 +76,19 @@ public function plan(): array {
 				continue;
 			}
 
+			// dirs[0] === '' means the source is a genuine root upload (no
+			// year/month directory, or the whole site has them switched
+			// off), so the flat path this candidate already sits at IS its
+			// final location — there is nothing to move. Building $target
+			// anyway would join in an empty path segment: the double slash
+			// collapses and $target resolves to $absolute itself, so
+			// is_file() on it is always true and would otherwise misreport
+			// every such file as a conflict with itself.
+			if ( '' === $dirs[0] ) {
+				$already_in_place[] = $relative;
+				continue;
+			}
+
 			$target = $this->cache_dir . '/' . $size_dir . '/' . $dirs[0] . '/' . $filename;
 
 			if ( is_file( $target ) ) {
@@ -85,10 +100,11 @@ public function plan(): array {
 		}
 
 		return array(
-			'move'      => $move,
-			'ambiguous' => $ambiguous,
-			'orphaned'  => $orphaned,
-			'conflict'  => $conflict,
+			'move'             => $move,
+			'ambiguous'        => $ambiguous,
+			'orphaned'         => $orphaned,
+			'conflict'         => $conflict,
+			'already_in_place' => $already_in_place,
 		);
 	}
 
@@ -98,7 +114,7 @@ public function plan(): array {
 	 * within the same filesystem, so the move is atomic and an interrupted run
 	 * leaves no partial file.
 	 *
-	 * @param array{move: array<string,string>, ambiguous: array<string, list<string>>, orphaned: list<string>, conflict: list<string>} $plan
+	 * @param array{move: array<string,string>, ambiguous: array<string, list<string>>, orphaned: list<string>, conflict: list<string>, already_in_place: list<string>} $plan
 	 * @return array{moved: int, failed: list<string>}
 	 */
 	public function apply( array $plan ): array {
diff --git a/tests/Unit/Cli/MigrateImageCacheCommandBuildNameToDirsTest.php b/tests/Unit/Cli/MigrateImageCacheCommandBuildNameToDirsTest.php
new file mode 100644
index 0000000..46bdca4
--- /dev/null
+++ b/tests/Unit/Cli/MigrateImageCacheCommandBuildNameToDirsTest.php
@@ -0,0 +1,117 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Cli;
+
+use Brain\Monkey;
+use Brain\Monkey\Functions;
+use Parisek\TimberKit\Cli\MigrateImageCacheCommand;
+use Parisek\TimberKit\ImageCacheMigrator;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * `buildNameToDirs()` is private and reads `$wpdb` directly, so it is
+ * exercised here through reflection with a stub `$wpdb`, rather than through
+ * `__invoke()` (WP_CLI I/O, deliberately not unit-tested per the class
+ * docblock).
+ *
+ * The scenario below is the one in
+ * `docs/adr/0007-resizer-source-path-cache-key.md`: a directory
+ * `guardSourceDir()` rejects must not simply vanish from the map, because
+ * the flag-enabled `Resizer` keeps that attachment's derivative at the flat
+ * cache key exactly like a genuine root upload does. If the rejected
+ * directory is dropped instead of folded into the flat key, a real
+ * collision at that flat key reads as an unambiguous move and corrupts a
+ * sibling attachment's derivative.
+ */
+class MigrateImageCacheCommandBuildNameToDirsTest extends TestCase {
+
+	protected function setUp(): void {
+		parent::setUp();
+		Monkey\setUp();
+
+		// Same stub shape as guardSourceDir's own test: keep A-Za-z0-9._-,
+		// strip the rest, so `'aug ust'` (a space) fails the guard.
+		Functions\when( 'sanitize_file_name' )->alias( function ( $name ) {
+			return preg_replace( '/[^A-Za-z0-9._-]/', '', (string) $name );
+		} );
+	}
+
+	protected function tearDown(): void {
+		unset( $GLOBALS['wpdb'] );
+		Monkey\tearDown();
+		parent::tearDown();
+	}
+
+	/**
+	 * @param list<string> $attached_files
+	 */
+	private function stubWpdb( array $attached_files ): void {
+		$GLOBALS['wpdb'] = new class( $attached_files ) extends \wpdb {
+			public string $postmeta = 'wp_postmeta';
+
+			public function __construct( private readonly array $attached_files ) {
+			}
+
+			public function get_col( $query ) {
+				return $this->attached_files;
+			}
+		};
+	}
+
+	/** @return array<string, list<string>> */
+	private function buildNameToDirs(): array {
+		$command = new MigrateImageCacheCommand();
+		$method  = new \ReflectionMethod( $command, 'buildNameToDirs' );
+		$method->setAccessible( true );
+
+		return $method->invoke( $command );
+	}
+
+	public function test_rejected_directory_still_contributes_the_flat_key(): void {
+		// A: rejected directory ('aug ust' contains a space) -- the runtime
+		// keeps its derivative at the flat cache key.
+		// B: clean directory, same basename.
+		$this->stubWpdb( [ '2026/aug ust/hero.png', '2026/08/hero.jpg' ] );
+
+		$name_to_dirs = $this->buildNameToDirs();
+
+		$this->assertArrayHasKey( 'hero', $name_to_dirs );
+		$this->assertSame( [ '', '2026/08' ], $name_to_dirs['hero'] );
+	}
+
+	public function test_a_genuine_root_upload_still_maps_the_same_way(): void {
+		$this->stubWpdb( [ 'hero.png' ] );
+
+		$name_to_dirs = $this->buildNameToDirs();
+
+		$this->assertSame( [ '' ], $name_to_dirs['hero'] );
+	}
+
+	/**
+	 * The full interaction: a flat derivative shared between a
+	 * guard-rejected upload and a clean one must be reported ambiguous, not
+	 * silently moved into the clean upload's directory.
+	 */
+	public function test_flat_derivative_shared_with_a_rejected_directory_is_ambiguous_not_moved(): void {
+		$this->stubWpdb( [ '2026/aug ust/hero.png', '2026/08/hero.jpg' ] );
+
+		$name_to_dirs = $this->buildNameToDirs();
+
+		$cache_dir = sys_get_temp_dir() . '/tk-cache-' . bin2hex( random_bytes( 6 ) );
+		mkdir( $cache_dir . '/900x0-center', 0777, true );
+		file_put_contents( $cache_dir . '/900x0-center/hero.avif', 'x' );
+
+		try {
+			$plan = ( new ImageCacheMigrator( $cache_dir, $name_to_dirs ) )->plan();
+
+			$this->assertSame( [], $plan['move'] );
+			$this->assertSame( [ '', '2026/08' ], $plan['ambiguous']['900x0-center/hero.avif'] );
+		} finally {
+			unlink( $cache_dir . '/900x0-center/hero.avif' );
+			rmdir( $cache_dir . '/900x0-center' );
+			rmdir( $cache_dir );
+		}
+	}
+}
diff --git a/tests/Unit/ImageCacheMigrator/MigratePlanTest.php b/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
index 52ea549..0803982 100644
--- a/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
+++ b/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
@@ -81,6 +81,25 @@ public function test_already_migrated_file_is_left_alone(): void {
 		$this->assertSame( [], $plan['orphaned'] );
 	}
 
+	/**
+	 * dirs[0] === '' means a genuine root upload -- the flat cache path IS
+	 * the final location already (no year/month directory, or the flag-off
+	 * byte-identical case from the ADR). `<cache>/<size>//<filename>`
+	 * collapses to the source file itself, so a naive is_file() check would
+	 * call every such file its own conflict. It must instead be recognised
+	 * as already in place: not moved, not reported as a conflict.
+	 */
+	public function test_root_upload_flat_derivative_is_already_in_place_not_a_conflict(): void {
+		$this->seed( '900x0-center/hero.avif' );
+		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '' ] ] ) )->plan();
+
+		$this->assertSame( [], $plan['move'] );
+		$this->assertSame( [], $plan['conflict'] );
+		$this->assertSame( [], $plan['orphaned'] );
+		$this->assertSame( [], $plan['ambiguous'] );
+		$this->assertSame( [ '900x0-center/hero.avif' ], $plan['already_in_place'] );
+	}
+
 	public function test_apply_moves_the_file_and_a_second_run_finds_nothing(): void {
 		$src = $this->seed( '900x0-center/hero.avif' );
 		$migrator = new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] );

From d8db562da7b488773d08e096b0d122b0c179af56 Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Wed, 26 Aug 2026 23:58:29 +0200
Subject: [PATCH 11/16] docs(image-cache-migrator): note the backslash
 input-domain and drop a leftover plan note

guardSourceDir() (MigrateImageCacheCommand) and
guarded_cached_derivative_source_dir() (StarterBase) both split on '/'
without normalizing backslashes first, unlike Resizer::sourcePathSegment(),
which reads a URL. Both guards read dirname() of _wp_attached_file, a
database value WordPress always stores forward-slash, so a backslash
cannot reach either guard; documented that with a matching comment in
both methods rather than adding unreachable normalization code.

Also removes an authoring-plan leftover sentence from
SourcePathCacheKeyTest's cacheKeysFor() docblock.
---
 src/StarterBase.php                           | 4 ++++
 tests/Unit/Resizer/SourcePathCacheKeyTest.php | 2 +-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/StarterBase.php b/src/StarterBase.php
index 86fe9a6..7d43da5 100644
--- a/src/StarterBase.php
+++ b/src/StarterBase.php
@@ -4066,6 +4066,10 @@ private function guarded_cached_derivative_source_dir( $dir ) {
 			return '';
 		}
 
+		// No backslash normalization here, unlike Resizer::sourcePathSegment()
+		// (which reads a URL): this reads dirname() of `_wp_attached_file`,
+		// a database value WordPress always stores with forward slashes, so
+		// a backslash cannot occur in this input domain.
 		$parts = [];
 
 		foreach ( explode( '/', $dir ) as $part ) {
diff --git a/tests/Unit/Resizer/SourcePathCacheKeyTest.php b/tests/Unit/Resizer/SourcePathCacheKeyTest.php
index cc8bfd1..2765f44 100644
--- a/tests/Unit/Resizer/SourcePathCacheKeyTest.php
+++ b/tests/Unit/Resizer/SourcePathCacheKeyTest.php
@@ -49,7 +49,7 @@ public function test_two_sources_sharing_a_name_get_different_keys(): void {
 
 	/**
 	 * Returns the cache_key of each normalized variant after resize() has
-	 * augmented it. Implemented in Step 3 of this task.
+	 * augmented it.
 	 *
 	 * @return list<string>
 	 */

From dc1bf057eab7693022eb63e650102df1ade0f71b Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Thu, 27 Aug 2026 07:48:39 +0200
Subject: [PATCH 12/16] docs(adr): key the derivative by the source's whole
 identity, extension included

---
 .../adr/0007-resizer-source-path-cache-key.md | 27 ++++++++++++++++---
 1 file changed, 23 insertions(+), 4 deletions(-)

diff --git a/docs/adr/0007-resizer-source-path-cache-key.md b/docs/adr/0007-resizer-source-path-cache-key.md
index 8720ed8..2835dd9 100644
--- a/docs/adr/0007-resizer-source-path-cache-key.md
+++ b/docs/adr/0007-resizer-source-path-cache-key.md
@@ -11,7 +11,9 @@ So the cache namespace is flatter than the namespace it caches — flatter twice
 over, because the derivative is named for the source *without its extension*, so
 `11.png` and `11.jpg` land on one path as surely as two `11.png` in different
 months do. Measured on a five-language production site: **496 names map to more
-than one source file**.
+than one source file, and 152 of those collide inside a single directory** —
+same name, different extension. The two axes are independent, and a fix that
+addresses only one leaves the other exactly as it was.
 
 ```
 900x0-center/11.avif   <-  2022/03/11.png
@@ -38,13 +40,23 @@ trading one silent collision for a subtler one.
 
 ## Decision
 
-Insert the source file's own directory — its path below the uploads root, with
-no leading or trailing separator — between the size directory and the filename:
+Key the derivative by the source's **whole identity** — its directory below the
+uploads root, and its full filename including the source's own extension:
 
 ```
-<W>x<H>-<style>[-q<N>]/<source-relative-dir>/<name>.<fmt>
+<W>x<H>-<style>[-q<N>]/<source-relative-dir>/<source-filename>.<fmt>
 ```
 
+So `uploads/2026/08/hero.webp` at 900px wide becomes
+`900x0-center/2026/08/hero.webp.avif`.
+
+Both halves are load-bearing and neither substitutes for the other. The
+directory separates `2022/03/11.png` from `2022/10/11.png`; the retained source
+extension separates `hero.jpg` from `hero.png` in one directory. Dropping either
+half leaves one of the two collision axes untouched — and the 152 same-directory
+collisions measured above are the half that is easy to forget, because adding a
+directory *feels* like it has separated everything.
+
 It is derived from `$source_path`, which `resize()` already computes; no new
 input and no filename parsing. `Resizer` maps a URL to a path only through the
 uploads base pair, so every source it caches lies below the uploads root and the
@@ -79,6 +91,13 @@ it means to delete instead of matching names. The sibling-attachment guard stays
 one file can carry several attachment rows under WPML, and that is independent
 of how the path is spelled.
 
+A note on how this decision was reached, because it is the point of the
+practice rather than a detail of it: the first version of this ADR added only
+the directory, and seven review rounds passed it. The same-directory half was
+found by an independent reviewer on a different model, reading the branch
+without sight of those rounds — the one thing the repo's own two-reviewer rule
+asks for and the one thing that run had skipped.
+
 The migration cannot place a derivative whose name maps to more than one
 source — recovering that association is exactly what the old layout destroyed.
 Those files are reported and left alone; the new path is empty for them, so they

From d9381358ff4ba98a06add45ad4f9307c0a0dfcc8 Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Thu, 27 Aug 2026 08:27:08 +0200
Subject: [PATCH 13/16] fix(resizer): key cache derivative on source filename
 including extension

Retains the source's own extension in the derivative filename whenever
StarterBase::$resizer_source_path_in_cache_key is on, so hero.jpg and
hero.png sharing one upload directory no longer collide on one
derivative name -- the directory-only fix left 152 of 496 measured
production collisions (same directory, different extension) unaddressed.
Flag off stays byte-identical to today.

Updates the four components that must agree on the new shape: the
writer (Resizer::resizer()), the deleter
(StarterBase::cached_derivative_paths_by_source_path()), and the
migrator's map (MigrateImageCacheCommand::buildNameToSourcePaths(),
renamed from buildNameToDirs()) and planner (ImageCacheMigrator::plan()).
The migrator's map now carries full source paths, not bare directories,
because the target filename needs the source's own extension; two
sources sharing a directory and stem but not an extension are recorded
as distinct candidates, so a legacy flat derivative they both map to is
reported ambiguous and left unmigrated rather than guessed.

Also, from the same review round:

- ImageCacheMigrator::apply() moves via link()+unlink() instead of an
  is_file() check followed by rename() -- POSIX rename() silently
  overwrites an existing destination, and a target could appear in the
  gap between the check and the syscall. link() fails atomically when
  the target exists, leaving both files untouched; only a successful
  link() is followed by unlink() of the source.
- MigrateImageCacheCommand::__invoke() now warns about every failed
  move, then calls WP_CLI::error() (non-zero exit) when any failed,
  and WP_CLI::success() only when none did -- it previously called
  success() unconditionally before the failure warnings, so a script
  harness reading only the exit code saw 0 on a run that left files
  unmoved.

CHANGELOG.md and README.md corrected to state precisely what the flag
resolves (directory and same-directory-extension collisions) versus
what it cannot (ambiguous flat-legacy names, left unmigrated).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Su5MBeKhMxER2XEcba6Qpt (petr@pari.cz)
---
 CHANGELOG.md                                  |  60 +++++--
 README.md                                     |   2 +-
 src/Cli/MigrateImageCacheCommand.php          |  88 ++++++----
 src/ImageCacheMigrator.php                    | 140 ++++++++++------
 src/Resizer.php                               |  10 +-
 src/StarterBase.php                           |   7 +-
 ...teImageCacheCommandBuildNameToDirsTest.php | 117 -------------
 ...CacheCommandBuildNameToSourcePathsTest.php | 157 ++++++++++++++++++
 .../MigrateImageCacheCommandInvokeTest.php    | 143 ++++++++++++++++
 .../ImageCacheMigrator/MigratePlanTest.php    |  83 ++++++---
 .../Resizer/SourceExtensionCacheKeyTest.php   |  95 +++++++++++
 .../StarterBase/CleanupCachedImagesTest.php   |  48 ++++--
 tests/bootstrap.php                           |  45 +++++
 13 files changed, 734 insertions(+), 261 deletions(-)
 delete mode 100644 tests/Unit/Cli/MigrateImageCacheCommandBuildNameToDirsTest.php
 create mode 100644 tests/Unit/Cli/MigrateImageCacheCommandBuildNameToSourcePathsTest.php
 create mode 100644 tests/Unit/Cli/MigrateImageCacheCommandInvokeTest.php
 create mode 100644 tests/Unit/Resizer/SourceExtensionCacheKeyTest.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8c082e0..64e4696 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,25 +8,33 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Added
 
-- `StarterBase::$resizer_source_path_in_cache_key` (default `false`) puts the
-  source image's upload directory in the resizer cache key, so two uploads that
-  share a name stop sharing one cached derivative. Without it the derivative is
-  named for the source alone, so `2022/03/11.png` and `2022/10/11.png` — and
-  `11.png` and `11.jpg`, because the extension is dropped too — occupy one path,
-  and whichever renders first decides what the others show. Measured on a
-  five-language production site: 496 names map to more than one source file.
+- `StarterBase::$resizer_source_path_in_cache_key` (default `false`) keys the
+  resizer cache on the source's whole identity — its upload directory *and* its
+  own filename, extension included — so two uploads that share a name stop
+  sharing one cached derivative. Without it the derivative is named for the
+  source's directory-less, extension-less stem alone, so `2022/03/11.png` and
+  `2022/10/11.png` collide on directory, and `hero.jpg` and `hero.png` in one
+  directory collide on extension. Measured on a five-language production site:
+  496 names map to more than one source file, and 152 of those collide inside a
+  single directory (same name, different extension).
 
   Enabling it relocates every derivative whose source is below a year/month
-  directory; `wp timber-kit migrate-image-cache` (dry-run by default) moves the
-  existing cache into the new shape rather than re-encoding it. Derivatives whose
-  name maps to more than one source cannot be placed — recovering that
-  association is exactly what the flat layout destroyed — so they are reported
-  and left alone, and re-encoded on first view. A site with year/month folders
-  switched off gets byte-identical paths and needs no migration.
+  directory, or whose source shares a directory and stem with another upload of
+  a different extension; `wp timber-kit migrate-image-cache` (dry-run by
+  default) moves the existing cache into the new shape rather than re-encoding
+  it. What it resolves: directory collisions and same-directory
+  different-extension collisions, both under the flag. What it does not
+  resolve: a flat legacy derivative whose old (extension-less) name maps to more
+  than one distinct source path is reported as ambiguous and left unmigrated —
+  recovering which source it came from is exactly what the flat layout
+  destroyed — and is re-encoded correctly on first view instead. A site with
+  year/month folders switched off, and no such same-directory-extension
+  collision, gets byte-identical paths and needs no migration.
 
   With the flag on, `cleanup_cached_images()` addresses derivatives by path
   instead of matching basenames across the tree, so deleting an attachment can
-  no longer reach another upload's images.
+  no longer reach another upload's images — including one differing only by
+  extension in the same directory.
 
   Decision and alternatives: `docs/adr/0007-resizer-source-path-cache-key.md`.
 
@@ -55,10 +63,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
   the same zero a genuine "no siblings" answer gives, so the null and
   `last_error` are both checked rather than read as a count.
 
-  Not fixed here, and tracked separately: two different files that share a
-  basename across upload-year folders still collide in the flat cache
-  namespace, so deleting one can remove the other's derivative. That needs a
-  cache-naming change, not a guard.
+  Not fixed here: two different files that share a basename across upload-year
+  folders, or within one directory but differing only by extension, still
+  collide in the flat cache namespace, so deleting one can remove the other's
+  derivative. That needed a cache-naming change, not a guard — see
+  `$resizer_source_path_in_cache_key` above, opt-in for exactly that reason.
+
+- `wp timber-kit migrate-image-cache --apply` could silently overwrite a
+  derivative: it checked the target didn't exist, then `rename()`d into it, and
+  a target created in the gap between those two steps — a second invocation, a
+  file dropped by hand — was replaced without warning by POSIX `rename()`. It
+  now moves via `link()` then `unlink()`: `link()` fails atomically when the
+  target exists, so a race there is reported as a failed move with both files
+  left untouched, never a silent overwrite.
+
+- `wp timber-kit migrate-image-cache --apply` reported success even when some
+  moves failed — `WP_CLI::success()` ran unconditionally, before the loop that
+  warns about failures, so a script harness reading only the exit code saw 0 on
+  a run that left files unmoved. It now warns about every failure first, then
+  exits non-zero via `WP_CLI::error()` when any move failed, and calls
+  `WP_CLI::success()` only when none did.
 
 ## [1.42.0] - 2026-08-26
 
diff --git a/README.md b/README.md
index b509051..1bd2221 100644
--- a/README.md
+++ b/README.md
@@ -1097,7 +1097,7 @@ Available hooks:
 - `timber_kit_resizer_remote_variant_probe_timeout` — HTTP timeout for variant probes, default `2.0`
 - `timber_kit_resizer_remote_variant_probe_limit` — max remote variant probes per request, default `50`
 - `timber_kit_resizer_quality_in_cache_key` — put a variant's quality in its cache key, default `false` (also settable as `StarterBase::$resizer_quality_in_cache_key`). Without it, re-cutting the same dimensions at a different quality serves the previously generated file. Opt-in because switching it on relocates every non-default-quality variant: old cache files orphan and public URLs change.
-- `timber_kit_resizer_source_path_in_cache_key` — put the source image's upload directory in its cache key, default `false` (also settable as `StarterBase::$resizer_source_path_in_cache_key`). Without it, two uploads that share a name occupy one cache path and whichever renders first decides what the other one shows. Opt-in because switching it on relocates every derivative whose source is not at the uploads root: old cache files orphan and public URLs change. Run `wp timber-kit migrate-image-cache` to move them instead of re-encoding them.
+- `timber_kit_resizer_source_path_in_cache_key` — key the resizer cache on the source's whole identity, default `false` (also settable as `StarterBase::$resizer_source_path_in_cache_key`): its upload directory *and* its own filename, extension included. Without it, two uploads that share a directory-less, extension-less stem occupy one cache path and whichever renders first decides what the other one shows — that covers both `2022/03/11.png` vs. `2022/10/11.png` (directory) and `hero.jpg` vs. `hero.png` in one directory (extension). Opt-in because switching it on relocates every derivative whose source is not at the uploads root, or whose source shares a directory and stem with a different-extension upload: old cache files orphan and public URLs change. Run `wp timber-kit migrate-image-cache` to move them instead of re-encoding them — a flat legacy derivative whose old name maps to more than one distinct source is reported as ambiguous and left in place, since recovering which source it came from is exactly what the flat layout destroyed.
 - `timber_kit_resizer_aspect_tolerance` — tolerance band around 1:1 used by `Resizer::classifyAspect()` to decide whether a source qualifies as `square`, default `0.1`. Returning a smaller value (e.g. `0.05`) tightens the square band; returning a larger value (e.g. `0.2`) loosens it.
 
 ### Google Tag Manager
diff --git a/src/Cli/MigrateImageCacheCommand.php b/src/Cli/MigrateImageCacheCommand.php
index 16c39ef..6201028 100644
--- a/src/Cli/MigrateImageCacheCommand.php
+++ b/src/Cli/MigrateImageCacheCommand.php
@@ -11,10 +11,11 @@
  * derivatives into the source-path layout ahead of enabling
  * `StarterBase::$resizer_source_path_in_cache_key`.
  *
- * Thin adapter over {@see ImageCacheMigrator}: it builds the name-to-source-dir
- * map from `_wp_attached_file` and delegates every decision (unambiguous move,
- * ambiguous collision, orphan, conflict) to the migrator, which is
- * unit-tested. The WP_CLI I/O here is intentionally not unit-tested.
+ * Thin adapter over {@see ImageCacheMigrator}: it builds the
+ * name-to-source-paths map from `_wp_attached_file` and delegates every
+ * decision (unambiguous move, ambiguous collision, orphan, conflict) to the
+ * migrator, which is unit-tested. The WP_CLI I/O here is intentionally not
+ * unit-tested.
  */
 class MigrateImageCacheCommand {
 
@@ -28,7 +29,7 @@ class MigrateImageCacheCommand {
 	 *   it would do.
 	 *
 	 * [--verbose]
-	 * : List the ambiguous names with their candidate source directories.
+	 * : List the ambiguous names with their candidate source paths.
 	 *
 	 * ## EXAMPLES
 	 *
@@ -46,7 +47,7 @@ public function __invoke( $args, $assoc_args ) {
 
 		$cache_dir = untrailingslashit( trailingslashit( WP_CONTENT_DIR ) . 'cache/image' );
 
-		$migrator = new ImageCacheMigrator( $cache_dir, $this->buildNameToDirs() );
+		$migrator = new ImageCacheMigrator( $cache_dir, $this->buildNameToSourcePaths() );
 		$plan     = $migrator->plan();
 
 		$scanned = count( $plan['move'] ) + count( $plan['ambiguous'] ) + count( $plan['orphaned'] )
@@ -73,61 +74,78 @@ public function __invoke( $args, $assoc_args ) {
 
 		$result = $migrator->apply( $plan );
 
-		\WP_CLI::success( sprintf( 'Moved %d derivatives (%d failed).', $result['moved'], count( $result['failed'] ) ) );
-
+		// Warnings, then the exit-code-bearing call, in that order: a script
+		// harness reads only the exit code, and WP_CLI::success() reports 0
+		// regardless of what ran before it. Calling it while $result['failed']
+		// is non-empty would report success on a run that left files
+		// unmoved -- WP_CLI::error() exits non-zero instead.
 		foreach ( $result['failed'] as $source ) {
 			\WP_CLI::warning( sprintf( 'Failed to move %s.', $source ) );
 		}
+
+		if ( array() !== $result['failed'] ) {
+			\WP_CLI::error( sprintf( 'Moved %d derivatives (%d failed).', $result['moved'], count( $result['failed'] ) ) );
+			return;
+		}
+
+		\WP_CLI::success( sprintf( 'Moved %d derivatives (0 failed).', $result['moved'] ) );
 	}
 
 	/**
-	 * Build the cache-name => source-directories map from `_wp_attached_file`.
+	 * Build the cache-name => full-source-paths map from `_wp_attached_file`.
+	 *
+	 * The value is a full source identity -- directory and the source's own
+	 * filename, extension included -- not just a directory: the target
+	 * filename the migrator builds needs the source's extension too (ADR
+	 * 0007's amendment), so a bare directory can no longer carry enough
+	 * information on its own.
 	 *
-	 * Every directory goes through {@see guardSourceDir()} first. A directory
-	 * it rejects contributes '' to the name's candidate list -- the same
-	 * value a genuine root upload contributes -- rather than being dropped.
-	 * Both cases mean the same thing to the flag-enabled `Resizer`
-	 * (`Resizer::sourcePathSegment()`): the derivative stays at the flat
-	 * cache key. Dropping a rejected attachment instead would erase it from
-	 * the map entirely, so a real collision at that flat key -- another
-	 * attachment sharing the basename -- would look unambiguous and move a
-	 * derivative that in fact belongs to the dropped attachment.
+	 * The directory half still goes through {@see guardSourceDir()} first. A
+	 * directory it rejects contributes just the bare (sanitized) filename,
+	 * no directory prefix -- the same shape a genuine root upload
+	 * contributes -- rather than being dropped. Both cases mean the same
+	 * thing to the flag-enabled `Resizer` (`Resizer::sourcePathSegment()`):
+	 * the derivative stays at the flat cache key. Dropping a rejected
+	 * attachment instead would erase it from the map entirely, so a real
+	 * collision at that flat key -- another attachment sharing the basename
+	 * -- would look unambiguous and move a derivative that in fact belongs
+	 * to the dropped attachment.
+	 *
+	 * Deduped on the full source path, not the directory: two attachment
+	 * rows can point at one identical file (WPML files one row per
+	 * language), and that must collapse to one candidate, not read as an
+	 * ambiguous pair.
 	 *
 	 * @return array<string, list<string>>
 	 */
-	private function buildNameToDirs(): array {
+	private function buildNameToSourcePaths(): array {
 		global $wpdb;
 
 		$rows = $wpdb->get_col( "SELECT meta_value FROM {$wpdb->postmeta} WHERE meta_key = '_wp_attached_file'" );
 
-		$name_to_dirs = array();
+		$name_to_source_paths = array();
 
 		foreach ( $rows as $row ) {
 			if ( ! is_string( $row ) || '' === $row ) {
 				continue;
 			}
 
-			$name        = sanitize_file_name( pathinfo( basename( $row ), PATHINFO_FILENAME ) );
-			$source_dir  = dirname( $row );
-			$guarded_dir = self::guardSourceDir( $source_dir );
-
-			// guardSourceDir() returns '' both for a genuine root upload
-			// (dirname() === '.') and for a directory it rejects. Both cases
-			// contribute '' here rather than one of them being dropped: the
-			// property this map exists to detect is "does the runtime keep
-			// this derivative at the flat key", and a rejected directory has
-			// that property exactly as much as a root upload does.
+			$filename            = basename( $row );
+			$name                = sanitize_file_name( pathinfo( $filename, PATHINFO_FILENAME ) );
+			$guarded_dir         = self::guardSourceDir( dirname( $row ) );
+			$sanitized_filename  = sanitize_file_name( $filename );
+			$source_path         = '' === $guarded_dir ? $sanitized_filename : $guarded_dir . '/' . $sanitized_filename;
 
-			if ( ! isset( $name_to_dirs[ $name ] ) ) {
-				$name_to_dirs[ $name ] = array();
+			if ( ! isset( $name_to_source_paths[ $name ] ) ) {
+				$name_to_source_paths[ $name ] = array();
 			}
 
-			if ( ! in_array( $guarded_dir, $name_to_dirs[ $name ], true ) ) {
-				$name_to_dirs[ $name ][] = $guarded_dir;
+			if ( ! in_array( $source_path, $name_to_source_paths[ $name ], true ) ) {
+				$name_to_source_paths[ $name ][] = $source_path;
 			}
 		}
 
-		return $name_to_dirs;
+		return $name_to_source_paths;
 	}
 
 	/**
diff --git a/src/ImageCacheMigrator.php b/src/ImageCacheMigrator.php
index d16c73f..94becc3 100644
--- a/src/ImageCacheMigrator.php
+++ b/src/ImageCacheMigrator.php
@@ -7,36 +7,45 @@
 /**
  * Moves existing resizer cache derivatives from the flat layout
  * (`<size>/<name>.<fmt>`) into the source-path layout
- * (`<size>/<source-relative-dir>/<name>.<fmt>`) — see
+ * (`<size>/<source-relative-dir>/<source-filename>.<fmt>`) — see
  * `docs/adr/0007-resizer-source-path-cache-key.md`.
  *
- * The cache filename drops the source's own extension: a derivative is named
- * `pathinfo( basename( $src ), PATHINFO_FILENAME )` plus the *target* format,
- * so `hero.avif` in the cache is keyed by `hero`, not `hero.avif`. That is why
- * `11.png` and `11.jpg` collide as surely as two `11.png` in different months
- * do, and why the lookup map passed to the constructor is built the same way.
+ * The flat derivative is named `pathinfo( basename( $src ), PATHINFO_FILENAME )`
+ * plus the *target* format, so `hero.avif` in the cache is keyed by `hero`, not
+ * `hero.avif`. That is why `11.png` and `11.jpg` collide as surely as two
+ * `11.png` in different months do, and why the lookup map passed to the
+ * constructor is keyed the same (extension-stripped) way.
  *
- * A candidate name can map to more than one source directory (the collision
- * this ADR exists to fix). Recovering which source a flat derivative actually
- * came from is exactly what the old layout destroyed, so an ambiguous name is
- * reported, never guessed.
+ * The new layout keys on the source's whole identity, extension included, so
+ * the map's *values* must be full source paths (`_wp_attached_file`, e.g.
+ * `2026/08/hero.webp`) rather than bare directories — the target filename
+ * needs the source's own extension, not just its directory. A candidate name
+ * can still map to more than one distinct source path: two files sharing a
+ * directory and stem but not an extension (`hero.jpg` / `hero.png`) are two
+ * identities that collided under the old flat name. Recovering which one a
+ * flat derivative actually came from is exactly what the old layout
+ * destroyed, so an ambiguous name is reported, never guessed.
  */
 class ImageCacheMigrator {
 
 	/**
-	 * @param string                $cache_dir    Absolute path to the resizer
-	 *                                            cache root (holds the size
-	 *                                            directories directly).
-	 * @param array<string, list<string>> $name_to_dirs Cache name (source
+	 * @param string                      $cache_dir           Absolute path to
+	 *                                            the resizer cache root (holds
+	 *                                            the size directories directly).
+	 * @param array<string, list<string>> $name_to_source_paths Cache name (source
 	 *                                            basename without extension,
 	 *                                            run through
 	 *                                            `sanitize_file_name()`)
-	 *                                            mapped to its distinct
-	 *                                            source directories.
+	 *                                            mapped to its distinct full
+	 *                                            source paths (source-relative
+	 *                                            directory plus the source's
+	 *                                            own sanitized filename,
+	 *                                            extension included; '' directory
+	 *                                            means a root upload).
 	 */
 	public function __construct(
 		private readonly string $cache_dir,
-		private readonly array $name_to_dirs
+		private readonly array $name_to_source_paths
 	) {
 	}
 
@@ -60,37 +69,44 @@ public function plan(): array {
 		$already_in_place = array();
 
 		foreach ( $this->candidates() as $relative => $absolute ) {
-			$size_dir = dirname( $relative );
-			$filename = basename( $relative );
-			$name     = pathinfo( $filename, PATHINFO_FILENAME );
+			$size_dir      = dirname( $relative );
+			$filename      = basename( $relative );
+			$name          = pathinfo( $filename, PATHINFO_FILENAME );
+			$target_format = pathinfo( $filename, PATHINFO_EXTENSION );
 
-			$dirs = $this->name_to_dirs[ $name ] ?? array();
+			// Dedup here too: two attachment rows can share one full source
+			// path (WPML files one row per language against the same file),
+			// and that must read as one identity, not an ambiguous pair.
+			$source_paths = array_values( array_unique( $this->name_to_source_paths[ $name ] ?? array() ) );
 
-			if ( array() === $dirs ) {
+			if ( array() === $source_paths ) {
 				$orphaned[] = $relative;
 				continue;
 			}
 
-			if ( count( $dirs ) > 1 ) {
-				$ambiguous[ $relative ] = $dirs;
+			if ( count( $source_paths ) > 1 ) {
+				$ambiguous[ $relative ] = $source_paths;
 				continue;
 			}
 
-			// dirs[0] === '' means the source is a genuine root upload (no
-			// year/month directory, or the whole site has them switched
-			// off), so the flat path this candidate already sits at IS its
-			// final location — there is nothing to move. Building $target
-			// anyway would join in an empty path segment: the double slash
-			// collapses and $target resolves to $absolute itself, so
-			// is_file() on it is always true and would otherwise misreport
-			// every such file as a conflict with itself.
-			if ( '' === $dirs[0] ) {
+			$source_path = $source_paths[0];
+			$source_dir  = $this->dirOf( $source_path );
+			$source_name = basename( $source_path );
+
+			$target_filename = $source_name . '.' . $target_format;
+			$target          = '' === $source_dir
+				? $this->cache_dir . '/' . $size_dir . '/' . $target_filename
+				: $this->cache_dir . '/' . $size_dir . '/' . $source_dir . '/' . $target_filename;
+
+			// A root upload whose source has no extension of its own
+			// resolves to the exact path the candidate already sits at
+			// (the sole case the target filename equals the flat filename)
+			// -- there is nothing to move.
+			if ( $target === $absolute ) {
 				$already_in_place[] = $relative;
 				continue;
 			}
 
-			$target = $this->cache_dir . '/' . $size_dir . '/' . $dirs[0] . '/' . $filename;
-
 			if ( is_file( $target ) ) {
 				$conflict[] = $relative;
 				continue;
@@ -110,9 +126,17 @@ public function plan(): array {
 
 	/**
 	 * Execute a plan produced by {@see plan()}. Never deletes, never
-	 * overwrites — the target directory is created and the file is `rename()`d
-	 * within the same filesystem, so the move is atomic and an interrupted run
-	 * leaves no partial file.
+	 * overwrites.
+	 *
+	 * Moves via `link()` then `unlink()`, not `rename()`: POSIX `rename()`
+	 * silently replaces an existing destination, and a target can appear in
+	 * the gap between this method's own `is_file()` check and the syscall
+	 * that acts on it -- the exact TOCTOU window a plain existence check
+	 * cannot close. `link()` is atomic against that race: the filesystem
+	 * itself refuses to create a second name over an existing one, so it
+	 * either creates the new name or leaves everything untouched, never a
+	 * partial link. Only once the new name exists do we `unlink()` the old
+	 * one -- a failure there could leave the file linked twice, never zero.
 	 *
 	 * @param array{move: array<string,string>, ambiguous: array<string, list<string>>, orphaned: list<string>, conflict: list<string>, already_in_place: list<string>} $plan
 	 * @return array{moved: int, failed: list<string>}
@@ -122,27 +146,31 @@ public function apply( array $plan ): array {
 		$failed = array();
 
 		foreach ( $plan['move'] as $source => $target ) {
-			// plan() only snapshots the filesystem; by the time this loop
-			// reaches an entry, another process (a second invocation, a file
-			// dropped by hand) may have created the target since. rename()
-			// silently replaces an existing destination on POSIX, so the
-			// "never overwrites" rule needs this re-check right here, not
-			// just in plan().
-			if ( is_file( $target ) ) {
+			$target_dir = dirname( $target );
+
+			if ( ! is_dir( $target_dir ) && ! mkdir( $target_dir, 0777, true ) && ! is_dir( $target_dir ) ) {
 				$failed[] = $source;
 				continue;
 			}
 
-			$target_dir = dirname( $target );
-
-			if ( ! is_dir( $target_dir ) && ! mkdir( $target_dir, 0777, true ) && ! is_dir( $target_dir ) ) {
+			// link() fails outright (returns false, raises no fatal) when
+			// $target already exists -- the plan()-time snapshot is stale by
+			// then, another invocation or a hand-placed file got there
+			// first. That failure leaves both $source and $target exactly
+			// as they were, so there is nothing to unwind: no fallback
+			// rename(), which would reopen the very race this replaces.
+			if ( ! @link( $source, $target ) ) {
 				$failed[] = $source;
 				continue;
 			}
 
-			if ( rename( $source, $target ) ) {
+			if ( unlink( $source ) ) {
 				++$moved;
 			} else {
+				// The new name exists and the old one didn't go away: not a
+				// data-loss case (both copies are intact), but not a clean
+				// move either, so it is reported rather than silently
+				// counted as done.
 				$failed[] = $source;
 			}
 		}
@@ -153,6 +181,20 @@ public function apply( array $plan ): array {
 		);
 	}
 
+	/**
+	 * `dirname()` of a relative path, normalized so "no directory" is '' —
+	 * `dirname()` itself returns '.' for a bare filename, which would
+	 * otherwise be joined into the target path as a literal segment.
+	 *
+	 * @param string $relative_path e.g. `2026/08/hero.webp` or `hero.webp`.
+	 * @return string
+	 */
+	private function dirOf( string $relative_path ): string {
+		$dir = dirname( $relative_path );
+
+		return '.' === $dir ? '' : $dir;
+	}
+
 	/**
 	 * Files sitting directly inside a size directory (`<cache>/<size>/<file>`).
 	 * Anything deeper already carries a source-relative-dir segment and is
diff --git a/src/Resizer.php b/src/Resizer.php
index 417a091..01365d8 100644
--- a/src/Resizer.php
+++ b/src/Resizer.php
@@ -1352,8 +1352,14 @@ public function resizer( $image, array $variants ): array {
 		$basedir = $upload_dir['basedir'];
 		$baseurl = $upload_dir['baseurl'];
 
-		// Sanitize filename to prevent path traversal attacks
-		$filename = sanitize_file_name( pathinfo( basename( $default_image['src'] ), PATHINFO_FILENAME ) );
+		// Sanitize filename to prevent path traversal attacks.
+		//
+		// Stripped of its extension by default — flag on keeps it (ADR 0007):
+		// the derivative name must carry the source's own extension too, or
+		// hero.jpg and hero.png in one directory collide on one derivative.
+		$filename = $this->source_path_in_cache_key
+			? sanitize_file_name( basename( $default_image['src'] ) )
+			: sanitize_file_name( pathinfo( basename( $default_image['src'] ), PATHINFO_FILENAME ) );
 
 		// Get actual source file path by converting URL to filesystem path
 		$source_path = str_replace( $baseurl, $basedir, $default_image['src'] );
diff --git a/src/StarterBase.php b/src/StarterBase.php
index 7d43da5..93cd26b 100644
--- a/src/StarterBase.php
+++ b/src/StarterBase.php
@@ -4014,7 +4014,12 @@ private function cached_derivative_paths_by_source_path( $cache_dir, $attachment
 		// glob() as a live pattern instead of a literal filename — matching
 		// whatever else happens to sit in that character class or wildcard.
 		// A name that sanitizes to nothing can't be resolved either way.
-		$name = sanitize_file_name( pathinfo( $relative_path, PATHINFO_FILENAME ) );
+		//
+		// The full basename, extension included: ADR 0007 keys the derivative
+		// on the source's whole identity, because two sources sharing a
+		// directory and a stem but not an extension (hero.jpg / hero.png)
+		// would otherwise resolve to the same derivative name here too.
+		$name = sanitize_file_name( basename( $relative_path ) );
 
 		if ( '' === $name ) {
 			return [];
diff --git a/tests/Unit/Cli/MigrateImageCacheCommandBuildNameToDirsTest.php b/tests/Unit/Cli/MigrateImageCacheCommandBuildNameToDirsTest.php
deleted file mode 100644
index 46bdca4..0000000
--- a/tests/Unit/Cli/MigrateImageCacheCommandBuildNameToDirsTest.php
+++ /dev/null
@@ -1,117 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Tests\Unit\Cli;
-
-use Brain\Monkey;
-use Brain\Monkey\Functions;
-use Parisek\TimberKit\Cli\MigrateImageCacheCommand;
-use Parisek\TimberKit\ImageCacheMigrator;
-use PHPUnit\Framework\TestCase;
-
-/**
- * `buildNameToDirs()` is private and reads `$wpdb` directly, so it is
- * exercised here through reflection with a stub `$wpdb`, rather than through
- * `__invoke()` (WP_CLI I/O, deliberately not unit-tested per the class
- * docblock).
- *
- * The scenario below is the one in
- * `docs/adr/0007-resizer-source-path-cache-key.md`: a directory
- * `guardSourceDir()` rejects must not simply vanish from the map, because
- * the flag-enabled `Resizer` keeps that attachment's derivative at the flat
- * cache key exactly like a genuine root upload does. If the rejected
- * directory is dropped instead of folded into the flat key, a real
- * collision at that flat key reads as an unambiguous move and corrupts a
- * sibling attachment's derivative.
- */
-class MigrateImageCacheCommandBuildNameToDirsTest extends TestCase {
-
-	protected function setUp(): void {
-		parent::setUp();
-		Monkey\setUp();
-
-		// Same stub shape as guardSourceDir's own test: keep A-Za-z0-9._-,
-		// strip the rest, so `'aug ust'` (a space) fails the guard.
-		Functions\when( 'sanitize_file_name' )->alias( function ( $name ) {
-			return preg_replace( '/[^A-Za-z0-9._-]/', '', (string) $name );
-		} );
-	}
-
-	protected function tearDown(): void {
-		unset( $GLOBALS['wpdb'] );
-		Monkey\tearDown();
-		parent::tearDown();
-	}
-
-	/**
-	 * @param list<string> $attached_files
-	 */
-	private function stubWpdb( array $attached_files ): void {
-		$GLOBALS['wpdb'] = new class( $attached_files ) extends \wpdb {
-			public string $postmeta = 'wp_postmeta';
-
-			public function __construct( private readonly array $attached_files ) {
-			}
-
-			public function get_col( $query ) {
-				return $this->attached_files;
-			}
-		};
-	}
-
-	/** @return array<string, list<string>> */
-	private function buildNameToDirs(): array {
-		$command = new MigrateImageCacheCommand();
-		$method  = new \ReflectionMethod( $command, 'buildNameToDirs' );
-		$method->setAccessible( true );
-
-		return $method->invoke( $command );
-	}
-
-	public function test_rejected_directory_still_contributes_the_flat_key(): void {
-		// A: rejected directory ('aug ust' contains a space) -- the runtime
-		// keeps its derivative at the flat cache key.
-		// B: clean directory, same basename.
-		$this->stubWpdb( [ '2026/aug ust/hero.png', '2026/08/hero.jpg' ] );
-
-		$name_to_dirs = $this->buildNameToDirs();
-
-		$this->assertArrayHasKey( 'hero', $name_to_dirs );
-		$this->assertSame( [ '', '2026/08' ], $name_to_dirs['hero'] );
-	}
-
-	public function test_a_genuine_root_upload_still_maps_the_same_way(): void {
-		$this->stubWpdb( [ 'hero.png' ] );
-
-		$name_to_dirs = $this->buildNameToDirs();
-
-		$this->assertSame( [ '' ], $name_to_dirs['hero'] );
-	}
-
-	/**
-	 * The full interaction: a flat derivative shared between a
-	 * guard-rejected upload and a clean one must be reported ambiguous, not
-	 * silently moved into the clean upload's directory.
-	 */
-	public function test_flat_derivative_shared_with_a_rejected_directory_is_ambiguous_not_moved(): void {
-		$this->stubWpdb( [ '2026/aug ust/hero.png', '2026/08/hero.jpg' ] );
-
-		$name_to_dirs = $this->buildNameToDirs();
-
-		$cache_dir = sys_get_temp_dir() . '/tk-cache-' . bin2hex( random_bytes( 6 ) );
-		mkdir( $cache_dir . '/900x0-center', 0777, true );
-		file_put_contents( $cache_dir . '/900x0-center/hero.avif', 'x' );
-
-		try {
-			$plan = ( new ImageCacheMigrator( $cache_dir, $name_to_dirs ) )->plan();
-
-			$this->assertSame( [], $plan['move'] );
-			$this->assertSame( [ '', '2026/08' ], $plan['ambiguous']['900x0-center/hero.avif'] );
-		} finally {
-			unlink( $cache_dir . '/900x0-center/hero.avif' );
-			rmdir( $cache_dir . '/900x0-center' );
-			rmdir( $cache_dir );
-		}
-	}
-}
diff --git a/tests/Unit/Cli/MigrateImageCacheCommandBuildNameToSourcePathsTest.php b/tests/Unit/Cli/MigrateImageCacheCommandBuildNameToSourcePathsTest.php
new file mode 100644
index 0000000..d3c28fa
--- /dev/null
+++ b/tests/Unit/Cli/MigrateImageCacheCommandBuildNameToSourcePathsTest.php
@@ -0,0 +1,157 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Cli;
+
+use Brain\Monkey;
+use Brain\Monkey\Functions;
+use Parisek\TimberKit\Cli\MigrateImageCacheCommand;
+use Parisek\TimberKit\ImageCacheMigrator;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * `buildNameToSourcePaths()` is private and reads `$wpdb` directly, so it is
+ * exercised here through reflection with a stub `$wpdb`, rather than through
+ * `__invoke()` (WP_CLI I/O, deliberately not unit-tested per the class
+ * docblock).
+ *
+ * ADR 0007's amendment: the map's values are full source paths (directory
+ * *and* the source's own filename, extension included), not bare
+ * directories -- the target filename needs the source's extension, and two
+ * sources sharing a directory and stem but differing only by extension
+ * (`hero.jpg` / `hero.png`) are two distinct identities that collided under
+ * one flat name.
+ */
+class MigrateImageCacheCommandBuildNameToSourcePathsTest extends TestCase {
+
+	protected function setUp(): void {
+		parent::setUp();
+		Monkey\setUp();
+
+		// Same stub shape as guardSourceDir's own test: keep A-Za-z0-9._-,
+		// strip the rest, so `'aug ust'` (a space) fails the guard.
+		Functions\when( 'sanitize_file_name' )->alias( function ( $name ) {
+			return preg_replace( '/[^A-Za-z0-9._-]/', '', (string) $name );
+		} );
+	}
+
+	protected function tearDown(): void {
+		unset( $GLOBALS['wpdb'] );
+		Monkey\tearDown();
+		parent::tearDown();
+	}
+
+	/**
+	 * @param list<string> $attached_files
+	 */
+	private function stubWpdb( array $attached_files ): void {
+		$GLOBALS['wpdb'] = new class( $attached_files ) extends \wpdb {
+			public string $postmeta = 'wp_postmeta';
+
+			public function __construct( private readonly array $attached_files ) {
+			}
+
+			public function get_col( $query ) {
+				return $this->attached_files;
+			}
+		};
+	}
+
+	/** @return array<string, list<string>> */
+	private function buildNameToSourcePaths(): array {
+		$command = new MigrateImageCacheCommand();
+		$method  = new \ReflectionMethod( $command, 'buildNameToSourcePaths' );
+		$method->setAccessible( true );
+
+		return $method->invoke( $command );
+	}
+
+	public function test_rejected_directory_still_contributes_the_flat_key(): void {
+		// A: rejected directory ('aug ust' contains a space) -- the runtime
+		// keeps its derivative at the flat cache key, so it contributes just
+		// the bare (sanitized) filename, no directory prefix.
+		// B: clean directory, same basename, different extension.
+		$this->stubWpdb( [ '2026/aug ust/hero.png', '2026/08/hero.jpg' ] );
+
+		$name_to_source_paths = $this->buildNameToSourcePaths();
+
+		$this->assertArrayHasKey( 'hero', $name_to_source_paths );
+		$this->assertSame( [ 'hero.png', '2026/08/hero.jpg' ], $name_to_source_paths['hero'] );
+	}
+
+	public function test_a_genuine_root_upload_still_maps_the_same_way(): void {
+		$this->stubWpdb( [ 'hero.png' ] );
+
+		$name_to_source_paths = $this->buildNameToSourcePaths();
+
+		$this->assertSame( [ 'hero.png' ], $name_to_source_paths['hero'] );
+	}
+
+	/**
+	 * Two sources in the same clean directory, same stem, different
+	 * extension: ADR 0007's own worked example of the same-directory
+	 * collision. Both must be recorded under the flat name, not
+	 * collapsed into one.
+	 */
+	public function test_same_directory_same_stem_different_extension_both_recorded(): void {
+		$this->stubWpdb( [ '2026/08/hero.jpg', '2026/08/hero.png' ] );
+
+		$name_to_source_paths = $this->buildNameToSourcePaths();
+
+		$this->assertSame( [ '2026/08/hero.jpg', '2026/08/hero.png' ], $name_to_source_paths['hero'] );
+	}
+
+	/**
+	 * The full interaction: a flat derivative shared between a
+	 * guard-rejected upload and a clean one must be reported ambiguous, not
+	 * silently moved into the clean upload's directory.
+	 */
+	public function test_flat_derivative_shared_with_a_rejected_directory_is_ambiguous_not_moved(): void {
+		$this->stubWpdb( [ '2026/aug ust/hero.png', '2026/08/hero.jpg' ] );
+
+		$name_to_source_paths = $this->buildNameToSourcePaths();
+
+		$cache_dir = sys_get_temp_dir() . '/tk-cache-' . bin2hex( random_bytes( 6 ) );
+		mkdir( $cache_dir . '/900x0-center', 0777, true );
+		file_put_contents( $cache_dir . '/900x0-center/hero.avif', 'x' );
+
+		try {
+			$plan = ( new ImageCacheMigrator( $cache_dir, $name_to_source_paths ) )->plan();
+
+			$this->assertSame( [], $plan['move'] );
+			$this->assertSame( [ 'hero.png', '2026/08/hero.jpg' ], $plan['ambiguous']['900x0-center/hero.avif'] );
+		} finally {
+			unlink( $cache_dir . '/900x0-center/hero.avif' );
+			rmdir( $cache_dir . '/900x0-center' );
+			rmdir( $cache_dir );
+		}
+	}
+
+	/**
+	 * Same directory, same stem, distinct source extensions -- ADR 0007's
+	 * worked example. Since recovering which source the flat `hero.avif`
+	 * actually came from is impossible, the migrator must leave it alone
+	 * rather than guess.
+	 */
+	public function test_ambiguous_by_extension_alone_is_left_unmigrated(): void {
+		$this->stubWpdb( [ '2026/08/hero.jpg', '2026/08/hero.png' ] );
+
+		$name_to_source_paths = $this->buildNameToSourcePaths();
+
+		$cache_dir = sys_get_temp_dir() . '/tk-cache-' . bin2hex( random_bytes( 6 ) );
+		mkdir( $cache_dir . '/900x0-center', 0777, true );
+		file_put_contents( $cache_dir . '/900x0-center/hero.avif', 'x' );
+
+		try {
+			$plan = ( new ImageCacheMigrator( $cache_dir, $name_to_source_paths ) )->plan();
+
+			$this->assertSame( [], $plan['move'] );
+			$this->assertArrayHasKey( '900x0-center/hero.avif', $plan['ambiguous'] );
+		} finally {
+			unlink( $cache_dir . '/900x0-center/hero.avif' );
+			rmdir( $cache_dir . '/900x0-center' );
+			rmdir( $cache_dir );
+		}
+	}
+}
diff --git a/tests/Unit/Cli/MigrateImageCacheCommandInvokeTest.php b/tests/Unit/Cli/MigrateImageCacheCommandInvokeTest.php
new file mode 100644
index 0000000..45c0ac3
--- /dev/null
+++ b/tests/Unit/Cli/MigrateImageCacheCommandInvokeTest.php
@@ -0,0 +1,143 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Cli;
+
+use Brain\Monkey;
+use Brain\Monkey\Functions;
+use Parisek\TimberKit\Cli\MigrateImageCacheCommand;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * `__invoke()`'s WP_CLI I/O is otherwise deliberately not unit-tested (see
+ * the class docblock) -- this test exists narrowly to pin the success/error
+ * exit-code ordering: a script harness reads only the exit code, and
+ * `WP_CLI::success()` reports 0 regardless of what ran before it.
+ * `WP_CLI::error()` halts (real WP_CLI exits non-zero), so it must run
+ * instead of, never alongside, `success()`.
+ *
+ * `WP_CONTENT_DIR` is a constant fixed once by the test bootstrap, so —
+ * unlike `MigrateImageCacheCommandInvokeTest`'s sibling tests — the cache
+ * directory here cannot be varied per test; it is cleaned up in place
+ * instead, the same pattern `CleanupCachedImagesTest` uses.
+ */
+class MigrateImageCacheCommandInvokeTest extends TestCase {
+
+	private string $cache_dir;
+
+	/** @var list<string> */
+	private array $created = [];
+
+	protected function setUp(): void {
+		parent::setUp();
+		Monkey\setUp();
+		\WP_CLI::reset();
+
+		Functions\when( 'sanitize_file_name' )->alias( function ( $name ) {
+			return preg_replace( '/[^A-Za-z0-9._-]/', '', (string) $name );
+		} );
+		Functions\when( 'untrailingslashit' )->alias( fn( $s ) => rtrim( (string) $s, '/' ) );
+		Functions\when( 'trailingslashit' )->alias( fn( $s ) => rtrim( (string) $s, '/' ) . '/' );
+
+		$this->cache_dir = WP_CONTENT_DIR . '/cache/image';
+		$this->makeDir( $this->cache_dir . '/900x0-center' );
+	}
+
+	protected function tearDown(): void {
+		// Directory permissions are restored before cleanup: a leftover
+		// 0555 directory from the error-path test would otherwise make its
+		// own removal fail.
+		foreach ( array_reverse( $this->created ) as $path ) {
+			if ( is_dir( $path ) ) {
+				chmod( $path, 0777 );
+			}
+		}
+		foreach ( array_reverse( $this->created ) as $path ) {
+			if ( is_file( $path ) ) {
+				unlink( $path );
+			} elseif ( is_dir( $path ) ) {
+				@rmdir( $path );
+			}
+		}
+		$this->created = [];
+		unset( $GLOBALS['wpdb'] );
+		\WP_CLI::reset();
+		Monkey\tearDown();
+		parent::tearDown();
+	}
+
+	/** Create $path and every missing parent, recording only what did not exist. */
+	private function makeDir( string $path ): void {
+		$missing = [];
+		for ( $dir = $path; ! is_dir( $dir ); $dir = dirname( $dir ) ) {
+			$missing[] = $dir;
+		}
+		mkdir( $path, 0777, true );
+		$this->created = array_merge( $this->created, array_reverse( $missing ) );
+	}
+
+	private function seedFile( string $path ): void {
+		file_put_contents( $path, 'x' );
+		$this->created[] = $path;
+	}
+
+	/** @param list<string> $attached_files */
+	private function stubWpdb( array $attached_files ): void {
+		$GLOBALS['wpdb'] = new class( $attached_files ) extends \wpdb {
+			public string $postmeta = 'wp_postmeta';
+
+			public function __construct( private readonly array $attached_files ) {
+			}
+
+			public function get_col( $query ) {
+				return $this->attached_files;
+			}
+		};
+	}
+
+	public function test_success_is_called_when_nothing_failed(): void {
+		$this->seedFile( $this->cache_dir . '/900x0-center/hero.avif' );
+		$this->stubWpdb( [ '2099/07/hero.webp' ] );
+
+		( new MigrateImageCacheCommand() )( [], [ 'apply' => true ] );
+
+		$this->assertSame( [], \WP_CLI::$errors );
+		$this->assertNotSame( [], \WP_CLI::$successes );
+		$this->assertSame( [], \WP_CLI::$warnings );
+
+		// seedFile() tracked the pre-move path for teardown; apply() moved
+		// it elsewhere, so track the real destination instead. Parent-first,
+		// matching makeDir()'s convention: tearDown() deletes in the reverse
+		// (child-first) order, and pushing this child-first here would flip
+		// that to parent-first at delete time, attempting rmdir() on a
+		// directory before the file inside it is gone.
+		$this->created[] = $this->cache_dir . '/900x0-center/2099';
+		$this->created[] = $this->cache_dir . '/900x0-center/2099/07';
+		$this->created[] = $this->cache_dir . '/900x0-center/2099/07/hero.webp.avif';
+	}
+
+	public function test_error_is_called_instead_of_success_when_something_failed(): void {
+		$this->seedFile( $this->cache_dir . '/900x0-center/hero.avif' );
+		// The target directory exists but is not writable -- link() must
+		// fail on the syscall itself (not the pre-existence check plan()
+		// already ran), apply() reports it as failed, and __invoke() must
+		// reflect that in its exit path instead of reporting success.
+		$this->makeDir( $this->cache_dir . '/900x0-center/2099/07' );
+		chmod( $this->cache_dir . '/900x0-center/2099/07', 0555 );
+
+		$this->stubWpdb( [ '2099/07/hero.webp' ] );
+
+		try {
+			( new MigrateImageCacheCommand() )( [], [ 'apply' => true ] );
+			$this->fail( 'expected WP_CLI::error() to halt the command' );
+		} catch ( \RuntimeException $e ) {
+			// Real WP_CLI::error() halts the same way -- exiting non-zero,
+			// never returning control to the caller.
+		}
+
+		$this->assertNotSame( [], \WP_CLI::$warnings, 'the failed move must be reported' );
+		$this->assertNotSame( [], \WP_CLI::$errors );
+		$this->assertSame( [], \WP_CLI::$successes, 'success must never fire alongside a failed move' );
+	}
+}
diff --git a/tests/Unit/ImageCacheMigrator/MigratePlanTest.php b/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
index 0803982..d84bc75 100644
--- a/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
+++ b/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
@@ -38,10 +38,10 @@ private function seed( string $relative ): string {
 
 	public function test_unambiguous_name_is_planned_for_a_move(): void {
 		$src = $this->seed( '900x0-center/hero.avif' );
-		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] ) )->plan();
+		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08/hero.webp' ] ] ) )->plan();
 
 		$this->assertSame(
-			[ $src => $this->dir . '/900x0-center/2026/08/hero.avif' ],
+			[ $src => $this->dir . '/900x0-center/2026/08/hero.webp.avif' ],
 			$plan['move']
 		);
 		$this->assertSame( [], $plan['ambiguous'] );
@@ -49,10 +49,10 @@ public function test_unambiguous_name_is_planned_for_a_move(): void {
 
 	public function test_ambiguous_name_is_reported_with_its_candidates(): void {
 		$this->seed( '900x0-center/11.avif' );
-		$plan = ( new ImageCacheMigrator( $this->dir, [ '11' => [ '2022/03', '2022/10' ] ] ) )->plan();
+		$plan = ( new ImageCacheMigrator( $this->dir, [ '11' => [ '2022/03/11.png', '2022/10/11.png' ] ] ) )->plan();
 
 		$this->assertSame( [], $plan['move'] );
-		$this->assertSame( [ '2022/03', '2022/10' ], $plan['ambiguous']['900x0-center/11.avif'] );
+		$this->assertSame( [ '2022/03/11.png', '2022/10/11.png' ], $plan['ambiguous']['900x0-center/11.avif'] );
 	}
 
 	public function test_name_absent_from_the_database_is_reported_as_orphaned(): void {
@@ -65,33 +65,30 @@ public function test_name_absent_from_the_database_is_reported_as_orphaned(): vo
 
 	public function test_existing_target_is_reported_as_a_conflict_not_overwritten(): void {
 		$this->seed( '900x0-center/hero.avif' );
-		$this->seed( '900x0-center/2026/08/hero.avif' );
-		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] ) )->plan();
+		$this->seed( '900x0-center/2026/08/hero.webp.avif' );
+		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08/hero.webp' ] ] ) )->plan();
 
 		$this->assertSame( [], $plan['move'] );
 		$this->assertSame( [ '900x0-center/hero.avif' ], $plan['conflict'] );
 	}
 
-	/** A file already in the new layout is not a candidate. */
+	/** A file already in the new layout is not a candidate -- it isn't sitting flat at the size-directory root. */
 	public function test_already_migrated_file_is_left_alone(): void {
-		$this->seed( '900x0-center/2026/08/hero.avif' );
-		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] ) )->plan();
+		$this->seed( '900x0-center/2026/08/hero.webp.avif' );
+		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08/hero.webp' ] ] ) )->plan();
 
 		$this->assertSame( [], $plan['move'] );
 		$this->assertSame( [], $plan['orphaned'] );
 	}
 
 	/**
-	 * dirs[0] === '' means a genuine root upload -- the flat cache path IS
-	 * the final location already (no year/month directory, or the flag-off
-	 * byte-identical case from the ADR). `<cache>/<size>//<filename>`
-	 * collapses to the source file itself, so a naive is_file() check would
-	 * call every such file its own conflict. It must instead be recognised
-	 * as already in place: not moved, not reported as a conflict.
+	 * A root upload whose own filename happens to carry no extension is the
+	 * one case where the new target filename equals the flat candidate's
+	 * filename byte-for-byte -- there is genuinely nothing to move.
 	 */
-	public function test_root_upload_flat_derivative_is_already_in_place_not_a_conflict(): void {
+	public function test_root_upload_with_extensionless_source_name_is_already_in_place(): void {
 		$this->seed( '900x0-center/hero.avif' );
-		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '' ] ] ) )->plan();
+		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ 'hero' ] ] ) )->plan();
 
 		$this->assertSame( [], $plan['move'] );
 		$this->assertSame( [], $plan['conflict'] );
@@ -100,33 +97,66 @@ public function test_root_upload_flat_derivative_is_already_in_place_not_a_confl
 		$this->assertSame( [ '900x0-center/hero.avif' ], $plan['already_in_place'] );
 	}
 
+	/**
+	 * A genuine root upload (no year/month directory) still gets its source
+	 * extension folded into the target name -- the flag adds the extension
+	 * unconditionally, independent of whether a directory segment applies.
+	 */
+	public function test_root_upload_with_extension_is_still_planned_for_a_move(): void {
+		$src = $this->seed( '900x0-center/hero.avif' );
+		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ 'hero.png' ] ] ) )->plan();
+
+		$this->assertSame(
+			[ $src => $this->dir . '/900x0-center/hero.png.avif' ],
+			$plan['move']
+		);
+	}
+
+	/**
+	 * ADR 0007's worked example: two sources sharing a directory and a stem
+	 * but not an extension collided under the old flat name, and recovering
+	 * which one `hero.avif` came from is exactly what that layout destroyed.
+	 * The migrator must report the ambiguity and move nothing, rather than
+	 * guess.
+	 */
+	public function test_same_directory_different_extension_is_ambiguous_and_left_unmigrated(): void {
+		$this->seed( '900x0-center/hero.avif' );
+		$plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08/hero.jpg', '2026/08/hero.png' ] ] ) )->plan();
+
+		$this->assertSame( [], $plan['move'] );
+		$this->assertSame(
+			[ '2026/08/hero.jpg', '2026/08/hero.png' ],
+			$plan['ambiguous']['900x0-center/hero.avif']
+		);
+	}
+
 	public function test_apply_moves_the_file_and_a_second_run_finds_nothing(): void {
 		$src = $this->seed( '900x0-center/hero.avif' );
-		$migrator = new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] );
+		$migrator = new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08/hero.webp' ] ] );
 
 		$result = $migrator->apply( $migrator->plan() );
 
 		$this->assertSame( 1, $result['moved'] );
 		$this->assertSame( [], $result['failed'] );
 		$this->assertFileDoesNotExist( $src );
-		$this->assertFileExists( $this->dir . '/900x0-center/2026/08/hero.avif' );
+		$this->assertFileExists( $this->dir . '/900x0-center/2026/08/hero.webp.avif' );
 
-		$this->assertSame( [], ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] ) )->plan()['move'] );
+		$this->assertSame( [], ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08/hero.webp' ] ] ) )->plan()['move'] );
 	}
 
 	/**
 	 * A target can appear between `plan()` snapshotting the filesystem and
-	 * `apply()` reaching that entry — another invocation, a manually placed
-	 * file, anything. `rename()` silently replaces an existing destination on
-	 * POSIX, so `apply()` must re-check immediately before calling it, not
-	 * trust the snapshot `plan()` took.
+	 * `apply()` reaching that entry -- another invocation, a manually placed
+	 * file, anything. `link()` fails outright when the target already
+	 * exists, so `apply()` is safe against this race without a separate
+	 * pre-check, and the source file must be left completely untouched.
 	 */
 	public function test_apply_does_not_overwrite_a_target_that_appeared_after_planning(): void {
 		$src = $this->seed( '900x0-center/hero.avif' );
-		$migrator = new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08' ] ] );
+		$migrator = new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08/hero.webp' ] ] );
 
 		$plan = $migrator->plan();
-		$target = $this->seed( '900x0-center/2026/08/hero.avif' );
+		$target = $this->seed( '900x0-center/2026/08/hero.webp.avif' );
 		file_put_contents( $target, 'pre-existing' );
 
 		$result = $migrator->apply( $plan );
@@ -134,6 +164,7 @@ public function test_apply_does_not_overwrite_a_target_that_appeared_after_plann
 		$this->assertSame( 0, $result['moved'] );
 		$this->assertSame( [ $src ], $result['failed'] );
 		$this->assertFileExists( $src );
+		$this->assertSame( 'x', file_get_contents( $src ) );
 		$this->assertSame( 'pre-existing', file_get_contents( $target ) );
 	}
 }
diff --git a/tests/Unit/Resizer/SourceExtensionCacheKeyTest.php b/tests/Unit/Resizer/SourceExtensionCacheKeyTest.php
new file mode 100644
index 0000000..24f7a58
--- /dev/null
+++ b/tests/Unit/Resizer/SourceExtensionCacheKeyTest.php
@@ -0,0 +1,95 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Resizer;
+
+use Brain\Monkey\Functions;
+use Tests\Unit\ResizerTestCase;
+
+/**
+ * ADR 0007's amendment: the flag must also retain the source's own
+ * extension in the derivative filename, not just its directory --
+ * `hero.jpg` and `hero.png` sharing a directory collided on one derivative
+ * name (`hero.avif`) even after the directory segment was added.
+ */
+class SourceExtensionCacheKeyTest extends ResizerTestCase {
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		Functions\when( 'wp_upload_dir' )->justReturn( [
+			'basedir' => '/var/www/html/wp-content/uploads',
+			'baseurl' => 'https://example.com/wp-content/uploads',
+		] );
+		Functions\when( 'sanitize_file_name' )->alias( function ( $name ) {
+			return preg_replace( '/[^A-Za-z0-9._-]/', '', (string) $name );
+		} );
+		Functions\when( 'content_url' )->alias( function ( $path ) {
+			return 'https://example.com/wp-content/' . $path;
+		} );
+		Functions\when( 'wp_check_filetype' )->alias( function ( $path ) {
+			if ( str_contains( $path, '.avif' ) ) {
+				return [ 'type' => 'image/avif', 'ext' => 'avif' ];
+			}
+			if ( str_contains( $path, '.png' ) ) {
+				return [ 'type' => 'image/png', 'ext' => 'png' ];
+			}
+			return [ 'type' => 'image/jpeg', 'ext' => 'jpg' ];
+		} );
+
+		// All variants "already cached" so processVariant() never reaches
+		// the encoder -- these tests assert the computed path, not pixels.
+		\Patchwork\redefine( 'file_exists', function ( string $path ) {
+			return true;
+		} );
+	}
+
+	protected function tearDown(): void {
+		\Patchwork\restoreAll();
+		parent::tearDown();
+	}
+
+	/** The flag off must keep dropping the source extension, byte-identical to today. */
+	public function test_flag_off_pins_the_extension_stripped_filename(): void {
+		$resizer = $this->createResizerWithSourcePathFlag( false );
+
+		$result = $resizer->resizer(
+			[ 'src' => 'https://example.com/wp-content/uploads/2026/08/hero.webp', 'width' => 100, 'height' => 100, 'alt' => '' ],
+			[ [ '900', '0', '', 'center' ] ]
+		);
+
+		$this->assertStringContainsString( '900x0-center/hero.avif', $result[0]['src'] );
+		$this->assertStringNotContainsString( 'hero.webp.avif', $result[0]['src'] );
+	}
+
+	/** The regression this amendment exists for: two sources, one directory, different extensions. */
+	public function test_flag_on_two_sources_sharing_a_directory_and_stem_get_different_filenames(): void {
+		$resizer = $this->createResizerWithSourcePathFlag( true );
+
+		$jpg = $resizer->resizer(
+			[ 'src' => 'https://example.com/wp-content/uploads/2026/08/hero.jpg', 'width' => 100, 'height' => 100, 'alt' => '' ],
+			[ [ '900', '0', '', 'center' ] ]
+		);
+		$png = $resizer->resizer(
+			[ 'src' => 'https://example.com/wp-content/uploads/2026/08/hero.png', 'width' => 100, 'height' => 100, 'alt' => '' ],
+			[ [ '900', '0', '', 'center' ] ]
+		);
+
+		$this->assertStringContainsString( '900x0-center/2026/08/hero.jpg.avif', $jpg[0]['src'] );
+		$this->assertStringContainsString( '900x0-center/2026/08/hero.png.avif', $png[0]['src'] );
+		$this->assertNotSame( $jpg[0]['src'], $png[0]['src'] );
+	}
+
+	/** ADR 0007's worked example. */
+	public function test_flag_on_matches_the_adr_worked_example(): void {
+		$resizer = $this->createResizerWithSourcePathFlag( true );
+
+		$result = $resizer->resizer(
+			[ 'src' => 'https://example.com/wp-content/uploads/2026/08/hero.webp', 'width' => 100, 'height' => 100, 'alt' => '' ],
+			[ [ '900', '0', '', 'center' ] ]
+		);
+
+		$this->assertStringContainsString( '900x0-center/2026/08/hero.webp.avif', $result[0]['src'] );
+	}
+}
diff --git a/tests/Unit/StarterBase/CleanupCachedImagesTest.php b/tests/Unit/StarterBase/CleanupCachedImagesTest.php
index 91d2bf8..4954b0d 100644
--- a/tests/Unit/StarterBase/CleanupCachedImagesTest.php
+++ b/tests/Unit/StarterBase/CleanupCachedImagesTest.php
@@ -231,21 +231,45 @@ public function test_with_the_flag_on_only_the_matching_source_directory_is_dele
 		mkdir( $this->cache_dir . '/900x0-center/2022/10', 0777, true );
 		$this->created[] = $this->cache_dir . '/900x0-center/2022/03';
 		$this->created[] = $this->cache_dir . '/900x0-center/2022/10';
-		$this->seedFile( $this->cache_dir . '/900x0-center/2022/03/11.avif' );
-		$this->seedFile( $this->cache_dir . '/900x0-center/2022/10/11.avif' );
+		$this->seedFile( $this->cache_dir . '/900x0-center/2022/03/11.png.avif' );
+		$this->seedFile( $this->cache_dir . '/900x0-center/2022/10/11.png.avif' );
 
 		$this->stubAttachment( 4711, '2022/03/11.png', siblings: 0 );
 		$this->enableSourcePathCacheKey();
 
 		$this->base->cleanup_cached_images( 4711 );
 
-		$this->assertFileDoesNotExist( $this->cache_dir . '/900x0-center/2022/03/11.avif' );
+		$this->assertFileDoesNotExist( $this->cache_dir . '/900x0-center/2022/03/11.png.avif' );
 		$this->assertFileExists(
-			$this->cache_dir . '/900x0-center/2022/10/11.avif',
+			$this->cache_dir . '/900x0-center/2022/10/11.png.avif',
 			'a different upload that happens to share a name must survive'
 		);
 	}
 
+	/**
+	 * ADR 0007's amendment: the extension is now part of the derivative
+	 * name too, so `11.jpg` and `11.png` sharing one directory no longer
+	 * collide on one derivative, and deleting one leaves the other's
+	 * derivative on disk untouched.
+	 */
+	public function test_with_the_flag_on_same_directory_different_extension_are_not_conflated(): void {
+		mkdir( $this->cache_dir . '/900x0-center/2026/08', 0777, true );
+		$this->created[] = $this->cache_dir . '/900x0-center/2026/08';
+		$this->seedFile( $this->cache_dir . '/900x0-center/2026/08/hero.jpg.avif' );
+		$this->seedFile( $this->cache_dir . '/900x0-center/2026/08/hero.png.avif' );
+
+		$this->stubAttachment( 4711, '2026/08/hero.jpg', siblings: 0 );
+		$this->enableSourcePathCacheKey();
+
+		$this->base->cleanup_cached_images( 4711 );
+
+		$this->assertFileDoesNotExist( $this->cache_dir . '/900x0-center/2026/08/hero.jpg.avif' );
+		$this->assertFileExists(
+			$this->cache_dir . '/900x0-center/2026/08/hero.png.avif',
+			'a sibling upload differing only by extension must survive'
+		);
+	}
+
 	/**
 	 * A raw (unsanitized) name used directly as a glob pattern turns a bracket
 	 * expression into a live character class. `img[0-9]` is a legitimate
@@ -261,8 +285,8 @@ public function test_with_the_flag_on_only_the_matching_source_directory_is_dele
 	public function test_with_the_flag_on_a_glob_metacharacter_in_the_name_does_not_reach_an_unrelated_derivative(): void {
 		mkdir( $this->cache_dir . '/900x0-center/2022/03', 0777, true );
 		$this->created[] = $this->cache_dir . '/900x0-center/2022/03';
-		$this->seedFile( $this->cache_dir . '/900x0-center/2022/03/img0-9.avif' );
-		$this->seedFile( $this->cache_dir . '/900x0-center/2022/03/img5.avif' );
+		$this->seedFile( $this->cache_dir . '/900x0-center/2022/03/img0-9.png.avif' );
+		$this->seedFile( $this->cache_dir . '/900x0-center/2022/03/img5.png.avif' );
 
 		$this->stubAttachment( 4711, '2022/03/img[0-9].png', siblings: 0 );
 		$this->enableSourcePathCacheKey();
@@ -270,11 +294,11 @@ public function test_with_the_flag_on_a_glob_metacharacter_in_the_name_does_not_
 		$this->base->cleanup_cached_images( 4711 );
 
 		$this->assertFileDoesNotExist(
-			$this->cache_dir . '/900x0-center/2022/03/img0-9.avif',
+			$this->cache_dir . '/900x0-center/2022/03/img0-9.png.avif',
 			'the target attachment\'s own (sanitized) derivative must still be found and deleted'
 		);
 		$this->assertFileExists(
-			$this->cache_dir . '/900x0-center/2022/03/img5.avif',
+			$this->cache_dir . '/900x0-center/2022/03/img5.png.avif',
 			'an unrelated upload must not be swept up by an unsanitized glob pattern'
 		);
 	}
@@ -290,7 +314,7 @@ public function test_with_the_flag_on_a_glob_metacharacter_in_the_name_does_not_
 	 */
 	public function test_with_the_flag_on_a_traversal_segment_in_the_directory_is_treated_as_the_flat_root(): void {
 		// The target's real derivative, at the flat root the guard falls back to.
-		$this->seedFile( $this->cache_dir . '/900x0-center/11.avif' );
+		$this->seedFile( $this->cache_dir . '/900x0-center/11.png.avif' );
 
 		// A file well outside the cache tree — a `..` component joined onto
 		// a size directory and walked by the filesystem can reach anything
@@ -299,7 +323,7 @@ public function test_with_the_flag_on_a_traversal_segment_in_the_directory_is_tr
 		// enumerating `$cache_dir`'s own subdirectories either.
 		$outside_dir = dirname( $this->cache_dir ) . '/decoy';
 		$this->makeDir( $outside_dir );
-		$this->seedFile( $outside_dir . '/11.avif' );
+		$this->seedFile( $outside_dir . '/11.png.avif' );
 
 		$this->stubAttachment( 4711, '../decoy/11.png', siblings: 0 );
 		$this->enableSourcePathCacheKey();
@@ -307,11 +331,11 @@ public function test_with_the_flag_on_a_traversal_segment_in_the_directory_is_tr
 		$this->base->cleanup_cached_images( 4711 );
 
 		$this->assertFileExists(
-			$outside_dir . '/11.avif',
+			$outside_dir . '/11.png.avif',
 			'a traversal segment must never let the delete walk outside the cache tree'
 		);
 		$this->assertFileDoesNotExist(
-			$this->cache_dir . '/900x0-center/11.avif',
+			$this->cache_dir . '/900x0-center/11.png.avif',
 			'the guard collapses the whole invalid directory to the flat root, matching the writer\'s own fallback'
 		);
 	}
diff --git a/tests/bootstrap.php b/tests/bootstrap.php
index dad9a8d..50025df 100644
--- a/tests/bootstrap.php
+++ b/tests/bootstrap.php
@@ -140,3 +140,48 @@ public function __construct( array|object $props = [] ) {
 		}
 	}
 }
+
+// Minimal WP_CLI stub recording every call instead of touching a real
+// terminal. `error()` throws, mirroring real WP_CLI: it halts the command
+// and (outside tests) exits non-zero, so code calling it must never expect
+// control to return -- exactly the ordering bug MigrateImageCacheCommand's
+// success/error fix depends on.
+if ( ! class_exists( 'WP_CLI' ) ) {
+	class WP_CLI {
+		/** @var list<string> */
+		public static array $logs = [];
+
+		/** @var list<string> */
+		public static array $warnings = [];
+
+		/** @var list<string> */
+		public static array $successes = [];
+
+		/** @var list<string> */
+		public static array $errors = [];
+
+		public static function reset(): void {
+			self::$logs      = [];
+			self::$warnings  = [];
+			self::$successes = [];
+			self::$errors    = [];
+		}
+
+		public static function log( $message ): void {
+			self::$logs[] = (string) $message;
+		}
+
+		public static function warning( $message ): void {
+			self::$warnings[] = (string) $message;
+		}
+
+		public static function success( $message ): void {
+			self::$successes[] = (string) $message;
+		}
+
+		public static function error( $message ): void {
+			self::$errors[] = (string) $message;
+			throw new \RuntimeException( (string) $message );
+		}
+	}
+}

From 60167ac78b289df87e183770441b2b79cfa058c8 Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Thu, 27 Aug 2026 08:45:24 +0200
Subject: [PATCH 14/16] fix(resizer): decode the URL filename before keying the
 cache

Resizer sanitized the still-encoded URL basename when building the
source-path cache key, while StarterBase::cached_derivative_paths_by_source_path()
and MigrateImageCacheCommand's map builder both name the source from the
decoded _wp_attached_file value. A space or percent-encoded character
made the writer and the deleter/migrator disagree on the derivative's
name -- 230 _wp_attached_file values on the measured production site
contain a space.

Strip the query string and rawurldecode() the basename once before
sanitizing, mirroring what Resizer::sourcePathSegment() already does
per path component for the directory half. The flag-off branch is
untouched.
---
 src/Resizer.php                               | 12 ++-
 .../Resizer/EncodedFilenameCacheKeyTest.php   | 95 +++++++++++++++++++
 2 files changed, 106 insertions(+), 1 deletion(-)
 create mode 100644 tests/Unit/Resizer/EncodedFilenameCacheKeyTest.php

diff --git a/src/Resizer.php b/src/Resizer.php
index 01365d8..831d957 100644
--- a/src/Resizer.php
+++ b/src/Resizer.php
@@ -1357,8 +1357,18 @@ public function resizer( $image, array $variants ): array {
 		// Stripped of its extension by default — flag on keeps it (ADR 0007):
 		// the derivative name must carry the source's own extension too, or
 		// hero.jpg and hero.png in one directory collide on one derivative.
+		//
+		// Flag on decodes the URL basename first, mirroring sourcePathSegment()'s
+		// handling of the directory half: $default_image['src'] is a URL, so a
+		// space or accented character is percent-encoded there but not in
+		// `_wp_attached_file`. StarterBase::cached_derivative_paths_by_source_path()
+		// and MigrateImageCacheCommand's map builder both name the source from
+		// the decoded DB value -- without decoding here too, the writer and the
+		// deleter/migrator name the same source differently and never agree.
+		// The flag-off branch is untouched: it must stay byte-for-byte identical
+		// to the previous behaviour.
 		$filename = $this->source_path_in_cache_key
-			? sanitize_file_name( basename( $default_image['src'] ) )
+			? sanitize_file_name( rawurldecode( basename( (string) strtok( $default_image['src'], '?' ) ) ) )
 			: sanitize_file_name( pathinfo( basename( $default_image['src'] ), PATHINFO_FILENAME ) );
 
 		// Get actual source file path by converting URL to filesystem path
diff --git a/tests/Unit/Resizer/EncodedFilenameCacheKeyTest.php b/tests/Unit/Resizer/EncodedFilenameCacheKeyTest.php
new file mode 100644
index 0000000..9f60283
--- /dev/null
+++ b/tests/Unit/Resizer/EncodedFilenameCacheKeyTest.php
@@ -0,0 +1,95 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Resizer;
+
+use Brain\Monkey\Functions;
+use Tests\Unit\ResizerTestCase;
+
+/**
+ * ADR 0007's derivative name must agree with the name
+ * `StarterBase::cached_derivative_paths_by_source_path()` and
+ * `MigrateImageCacheCommand`'s map builder compute from the decoded
+ * `_wp_attached_file` value -- otherwise the writer and the deleter/migrator
+ * name the same source differently and never find each other's file.
+ *
+ * `wp_upload_dir()['baseurl']` and an attachment's `src` are URLs, so a
+ * space or a non-ASCII character in the filename is percent-encoded there
+ * but not in the database. The filename half of the cache key must decode
+ * the URL first, exactly as `Resizer::sourcePathSegment()` already does for
+ * the directory half.
+ */
+class EncodedFilenameCacheKeyTest extends ResizerTestCase {
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		Functions\when( 'wp_upload_dir' )->justReturn( [
+			'basedir' => '/var/www/html/wp-content/uploads',
+			'baseurl' => 'https://example.com/wp-content/uploads',
+		] );
+		Functions\when( 'sanitize_file_name' )->alias( function ( $name ) {
+			return preg_replace( '/[^A-Za-z0-9._ -]/', '', (string) $name );
+		} );
+		Functions\when( 'content_url' )->alias( function ( $path ) {
+			return 'https://example.com/wp-content/' . $path;
+		} );
+		Functions\when( 'wp_check_filetype' )->alias( function ( $path ) {
+			unset( $path );
+			return [ 'type' => 'image/jpeg', 'ext' => 'jpg' ];
+		} );
+
+		\Patchwork\redefine( 'file_exists', function ( string $path ) {
+			return true;
+		} );
+	}
+
+	protected function tearDown(): void {
+		\Patchwork\restoreAll();
+		parent::tearDown();
+	}
+
+	/**
+	 * The measured production shape: 230 `_wp_attached_file` values contain a
+	 * space. The writer must name the derivative from the decoded name
+	 * (`My Photo.JPG`), matching what the deleter/migrator compute from the
+	 * DB value -- not from the still-encoded URL basename (`My%20Photo.JPG`).
+	 */
+	public function test_percent_encoded_space_decodes_before_sanitizing(): void {
+		$resizer = $this->createResizerWithSourcePathFlag( true );
+
+		$result = $resizer->resizer(
+			[ 'src' => 'https://example.com/wp-content/uploads/2026/08/My%20Photo.JPG', 'width' => 100, 'height' => 100, 'alt' => '' ],
+			[ [ '900', '0', '', 'center' ] ]
+		);
+
+		$this->assertStringContainsString( '900x0-center/2026/08/My Photo.JPG.avif', $result[0]['src'] );
+		$this->assertStringNotContainsString( 'My%20Photo.JPG', $result[0]['src'] );
+	}
+
+	/** UTF-8 percent-encoding (e.g. an accented character) must decode the same way. */
+	public function test_percent_encoded_utf8_decodes_before_sanitizing(): void {
+		$resizer = $this->createResizerWithSourcePathFlag( true );
+
+		$result = $resizer->resizer(
+			[ 'src' => 'https://example.com/wp-content/uploads/2026/08/caf%C3%A9.jpg', 'width' => 100, 'height' => 100, 'alt' => '' ],
+			[ [ '900', '0', '', 'center' ] ]
+		);
+
+		$this->assertStringNotContainsString( '%C3%A9', $result[0]['src'] );
+	}
+
+	/** A query string on the URL must not leak into the derivative's filename. */
+	public function test_query_string_is_stripped_before_sanitizing(): void {
+		$resizer = $this->createResizerWithSourcePathFlag( true );
+
+		$result = $resizer->resizer(
+			[ 'src' => 'https://example.com/wp-content/uploads/2026/08/hero.jpg?ver=123', 'width' => 100, 'height' => 100, 'alt' => '' ],
+			[ [ '900', '0', '', 'center' ] ]
+		);
+
+		$this->assertStringContainsString( '900x0-center/2026/08/hero.jpg.avif', $result[0]['src'] );
+		$this->assertStringNotContainsString( 'ver=123', $result[0]['src'] );
+	}
+}

From d6ddbc7fc23802ebb77a673cb7daa7c87f2d3f99 Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Thu, 27 Aug 2026 08:45:24 +0200
Subject: [PATCH 15/16] fix(migrator): classify an already-migrated root upload
 before the legacy lookup

A root upload's migrated derivative (hero.png.avif) sits at the same
depth in the size directory as an unmigrated legacy one, so a second
migration run re-scanned it, failed the legacy-name lookup (the map is
keyed by un-migrated names), and reported it orphaned.

Index every root-upload source by its own full name (extension
included) and merge that into the legacy lookup before counting
matches. A name resolving to the same single source under both
interpretations stays unambiguous; a name resolving to two distinct
identities -- a root upload and an unrelated legacy source whose
stripped name happens to coincide, ADR 0007's aliasing case -- is
reported ambiguous rather than guessed.

Also asserts the full plan (not just `move`) is empty on the existing
second-run idempotence test, since an orphaned/ambiguous bucket
populated would have passed the old, narrower assertion.
---
 src/ImageCacheMigrator.php                    | 60 ++++++++++++++++++-
 .../ImageCacheMigrator/MigratePlanTest.php    | 60 ++++++++++++++++++-
 2 files changed, 116 insertions(+), 4 deletions(-)

diff --git a/src/ImageCacheMigrator.php b/src/ImageCacheMigrator.php
index 94becc3..cc00bf5 100644
--- a/src/ImageCacheMigrator.php
+++ b/src/ImageCacheMigrator.php
@@ -28,6 +28,18 @@
  */
 class ImageCacheMigrator {
 
+	/**
+	 * Basename (own extension included) of every root-upload (no directory)
+	 * source path in `$name_to_source_paths`, mapped back to its distinct
+	 * full source paths. A root upload's migrated derivative sits at the same
+	 * depth in the size directory as an unmigrated legacy one -- this index
+	 * is what lets `plan()` tell "already produced by the new layout" apart
+	 * from "still a legacy name to migrate" without relying on path depth.
+	 *
+	 * @var array<string, list<string>>
+	 */
+	private readonly array $root_target_index;
+
 	/**
 	 * @param string                      $cache_dir           Absolute path to
 	 *                                            the resizer cache root (holds
@@ -47,6 +59,27 @@ public function __construct(
 		private readonly string $cache_dir,
 		private readonly array $name_to_source_paths
 	) {
+		$root_target_index = array();
+
+		foreach ( $this->name_to_source_paths as $source_paths ) {
+			foreach ( $source_paths as $source_path ) {
+				if ( '' !== $this->dirOf( $source_path ) ) {
+					continue;
+				}
+
+				$target_name = basename( $source_path );
+
+				if ( ! isset( $root_target_index[ $target_name ] ) ) {
+					$root_target_index[ $target_name ] = array();
+				}
+
+				if ( ! in_array( $source_path, $root_target_index[ $target_name ], true ) ) {
+					$root_target_index[ $target_name ][] = $source_path;
+				}
+			}
+		}
+
+		$this->root_target_index = $root_target_index;
 	}
 
 	/**
@@ -77,7 +110,25 @@ public function plan(): array {
 			// Dedup here too: two attachment rows can share one full source
 			// path (WPML files one row per language against the same file),
 			// and that must read as one identity, not an ambiguous pair.
-			$source_paths = array_values( array_unique( $this->name_to_source_paths[ $name ] ?? array() ) );
+			//
+			// The root-target index is merged in on purpose, not consulted
+			// separately: a root upload's own migrated derivative (e.g.
+			// `hero.png.avif`) sits at the very same depth in the size
+			// directory as an unmigrated legacy candidate, so `candidates()`
+			// cannot tell them apart by path shape alone. Folding both
+			// interpretations into one set before counting means a name that
+			// resolves the same way under both (the common case -- see
+			// `test_root_upload_with_extensionless_source_name_is_already_in_place`)
+			// still reads as unambiguous, while a name that resolves to two
+			// distinct identities (ADR 0007's aliasing case: `hero.png` the
+			// root upload vs. `hero.png.jpg` a legacy source -- both strip to
+			// `hero.png`) reads as ambiguous exactly as any other collision
+			// would. Recovering which one produced the file on disk is
+			// exactly what the flat layout destroyed.
+			$source_paths = array_values( array_unique( array_merge(
+				$this->root_target_index[ $name ] ?? array(),
+				$this->name_to_source_paths[ $name ] ?? array()
+			) ) );
 
 			if ( array() === $source_paths ) {
 				$orphaned[] = $relative;
@@ -197,8 +248,11 @@ private function dirOf( string $relative_path ): string {
 
 	/**
 	 * Files sitting directly inside a size directory (`<cache>/<size>/<file>`).
-	 * Anything deeper already carries a source-relative-dir segment and is
-	 * therefore already migrated, so it is not a candidate.
+	 * Anything deeper already carries a source-relative-dir segment, so it is
+	 * not a candidate. A file at this depth is not necessarily unmigrated,
+	 * though: a root upload's own migrated derivative lands here too (its
+	 * source-relative-dir is empty), so `plan()` -- not this method -- is
+	 * what tells the two apart, via `$root_target_index`.
 	 *
 	 * @return array<string,string> Relative path (from `$cache_dir`) => absolute path.
 	 */
diff --git a/tests/Unit/ImageCacheMigrator/MigratePlanTest.php b/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
index d84bc75..0703ec3 100644
--- a/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
+++ b/tests/Unit/ImageCacheMigrator/MigratePlanTest.php
@@ -141,7 +141,65 @@ public function test_apply_moves_the_file_and_a_second_run_finds_nothing(): void
 		$this->assertFileDoesNotExist( $src );
 		$this->assertFileExists( $this->dir . '/900x0-center/2026/08/hero.webp.avif' );
 
-		$this->assertSame( [], ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08/hero.webp' ] ] ) )->plan()['move'] );
+		$second_plan = ( new ImageCacheMigrator( $this->dir, [ 'hero' => [ '2026/08/hero.webp' ] ] ) )->plan();
+		$this->assertSame( [], $second_plan['move'] );
+		$this->assertSame( [], $second_plan['ambiguous'] );
+		$this->assertSame( [], $second_plan['orphaned'] );
+		$this->assertSame( [], $second_plan['conflict'] );
+	}
+
+	/**
+	 * A root upload's migrated derivative (`hero.png.avif`) sits at the same
+	 * depth in the size directory as an unmigrated legacy one -- path depth
+	 * alone cannot tell "already done" from "still to do". A second run must
+	 * recognise the migrated file as `already_in_place`, not misread it as an
+	 * orphan (its legacy stripped name `hero.png` isn't a key in the map,
+	 * which is keyed by the un-migrated legacy names).
+	 */
+	public function test_root_upload_with_extension_is_idempotent_on_a_second_run(): void {
+		$this->seed( '900x0-center/hero.avif' );
+		$name_to_source_paths = [ 'hero' => [ 'hero.png' ] ];
+		$migrator = new ImageCacheMigrator( $this->dir, $name_to_source_paths );
+
+		$first = $migrator->apply( $migrator->plan() );
+		$this->assertSame( 1, $first['moved'] );
+		$this->assertFileExists( $this->dir . '/900x0-center/hero.png.avif' );
+
+		$second_plan = ( new ImageCacheMigrator( $this->dir, $name_to_source_paths ) )->plan();
+		$this->assertSame( [], $second_plan['move'] );
+		$this->assertSame( [], $second_plan['ambiguous'] );
+		$this->assertSame( [], $second_plan['orphaned'] );
+		$this->assertSame( [], $second_plan['conflict'] );
+		$this->assertSame( [ '900x0-center/hero.png.avif' ], $second_plan['already_in_place'] );
+	}
+
+	/**
+	 * The genuine aliasing case ADR 0007 calls out: a new derivative for root
+	 * source `hero.png` has the same on-disk spelling as the OLD flat
+	 * derivative for a different root source, `hero.png.jpg` (whose legacy
+	 * name -- `pathinfo(..., PATHINFO_FILENAME)` strips only the last
+	 * extension -- is also `hero.png`). Recovering which one produced the
+	 * file on disk is exactly what the flat layout destroyed, so this must
+	 * be reported as ambiguous, never guessed.
+	 */
+	public function test_root_target_name_colliding_with_a_different_legacy_source_is_ambiguous(): void {
+		$this->seed( '900x0-center/hero.png.avif' );
+
+		// 'hero' => ['hero.png'] is the root source whose migrated derivative
+		// is the on-disk file. 'hero.png' => ['hero.png.jpg'] is an unrelated
+		// legacy source whose OWN stripped name (PATHINFO_FILENAME drops only
+		// the last extension) also happens to be 'hero.png'.
+		$plan = ( new ImageCacheMigrator(
+			$this->dir,
+			[ 'hero' => [ 'hero.png' ], 'hero.png' => [ 'hero.png.jpg' ] ]
+		) )->plan();
+
+		$this->assertSame( [], $plan['move'] );
+		$this->assertSame( [], $plan['already_in_place'] );
+		$this->assertSame(
+			[ 'hero.png', 'hero.png.jpg' ],
+			$plan['ambiguous']['900x0-center/hero.png.avif']
+		);
 	}
 
 	/**

From c3775b872f1373eac0c1e729e37a7f070a897b0e Mon Sep 17 00:00:00 2001
From: Petr Parimucha <petr@pari.cz>
Date: Thu, 27 Aug 2026 08:45:24 +0200
Subject: [PATCH 16/16] docs(adr): correct 0007's description of the old key
 and the new one

The old-name description in Context contradicted the correct one
already given lower in the same file (sanitize_file_name(basename())
vs the actual pathinfo(..., PATHINFO_FILENAME)). The Decision section
claimed the new key needs "no filename parsing", which the encoded-
filename fix in this branch makes explicitly false. The byte-identical-
path claim for folder-less sites didn't hold for a root upload with an
extension of its own -- only an extensionless root source produces one.
Consequences now also states the key's sanitization-derived (not
whole-identity) collision limit, and the idempotence claim reflects the
already-migrated-root-upload fix.
---
 CHANGELOG.md                                  |  8 +--
 .../adr/0007-resizer-source-path-cache-key.md | 54 ++++++++++++++-----
 2 files changed, 45 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 64e4696..6d1a730 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,9 +27,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
   resolve: a flat legacy derivative whose old (extension-less) name maps to more
   than one distinct source path is reported as ambiguous and left unmigrated —
   recovering which source it came from is exactly what the flat layout
-  destroyed — and is re-encoded correctly on first view instead. A site with
-  year/month folders switched off, and no such same-directory-extension
-  collision, gets byte-identical paths and needs no migration.
+  destroyed — and is re-encoded correctly on first view instead. A root upload
+  (no year/month directory) still needs migrating, because its target name now
+  carries the source's own extension too (`hero.avif` becomes `hero.png.avif`);
+  only a root upload whose source filename has no extension of its own
+  produces a byte-identical path, and needs no migration.
 
   With the flag on, `cleanup_cached_images()` addresses derivatives by path
   instead of matching basenames across the tree, so deleting an attachment can
diff --git a/docs/adr/0007-resizer-source-path-cache-key.md b/docs/adr/0007-resizer-source-path-cache-key.md
index 2835dd9..314cafb 100644
--- a/docs/adr/0007-resizer-source-path-cache-key.md
+++ b/docs/adr/0007-resizer-source-path-cache-key.md
@@ -3,9 +3,10 @@
 ## Context
 
 `Resizer` writes every derivative to `wp-content/cache/image/<W>x<H>-<style>/<name>.<fmt>`,
-where `<name>` is `sanitize_file_name( basename( $src ) )` — the source file's
-name with its directory thrown away. Uploads keep their directory: WordPress
-files them under `uploads/<year>/<month>/`.
+where `<name>` is `pathinfo( basename( $src ), PATHINFO_FILENAME )` run through
+`sanitize_file_name()` — the source file's name with its directory *and* its
+own extension thrown away. Uploads keep their directory: WordPress files them
+under `uploads/<year>/<month>/`.
 
 So the cache namespace is flatter than the namespace it caches — flatter twice
 over, because the derivative is named for the source *without its extension*, so
@@ -57,11 +58,19 @@ half leaves one of the two collision axes untouched — and the 152 same-directo
 collisions measured above are the half that is easy to forget, because adding a
 directory *feels* like it has separated everything.
 
-It is derived from `$source_path`, which `resize()` already computes; no new
-input and no filename parsing. `Resizer` maps a URL to a path only through the
-uploads base pair, so every source it caches lies below the uploads root and the
-segment is always well defined — possibly empty, never absent. A theme-directory
-image does not resolve and never reaches the cache.
+It is derived from the source's own URL, not `$source_path`: the directory half
+must be resolvable before `resize()` knows whether the local file exists (a
+missing source is served by a filter that addresses the same cache path on
+another host), and the filename half must agree with what
+`StarterBase::cached_derivative_paths_by_source_path()` and the migration
+command compute from `_wp_attached_file`. Both halves parse the URL the same
+way: strip the query string, decode each `%`-encoded component, then run it
+through `sanitize_file_name()` — a URL is encoded where the database value is
+not, so skipping the decode step would make the writer and the deleter/migrator
+name the same source differently. `Resizer` maps a URL to a path only through
+the uploads base pair, so every source it caches lies below the uploads root
+and the directory segment is always well defined — possibly empty, never
+absent. A theme-directory image does not resolve and never reaches the cache.
 
 The behaviour ships behind `StarterBase::$resizer_source_path_in_cache_key`
 (filter `timber_kit_resizer_source_path_in_cache_key`), default `false`,
@@ -79,18 +88,32 @@ uploads this is thousands of files; regenerating them costs encoder time, and on
 a host whose encoder is defective it costs correctness. The decision is the
 project's to take on its own schedule, not a consequence of `composer update`.
 
-Where a site has year/month folders switched off, the relative directory is
-empty and the path is byte-identical to the current one. Those sites enable the
-flag with no regeneration at all. That is a property of the scheme, not a goal
-of it, and the test suite pins it.
+Where a site has year/month folders switched off (a root upload), the relative
+directory is empty, but the path is *not* generally byte-identical to the
+current one: the target name still gains the source's own extension
+(`hero.avif` becomes `hero.png.avif`), so a root upload needs migrating too.
+The one exception is a root upload whose own filename already carries no
+extension — there the target and the current flat name coincide, and the test
+suite pins exactly that case, not the broader one.
 
-`<source-relative-dir>/<name>` is `_wp_attached_file` without its extension.
+`<source-relative-dir>/<source-filename>` is `_wp_attached_file` in full,
+extension included — not the extension-stripped form the flat layout used.
 A derivative's path therefore becomes **derivable from the database** rather than
 discoverable by scanning, which lets `cleanup_cached_images()` address the files
 it means to delete instead of matching names. The sibling-attachment guard stays:
 one file can carry several attachment rows under WPML, and that is independent
 of how the path is spelled.
 
+The key is built from `sanitize_file_name()`'s output, which is the *sanitized*
+identity of a source, not a guarantee of a unique one: two names differing only
+in characters that function strips (`hero[1].jpg` and `hero1.jpg`, in
+principle) would collide on one cache key. This is not engineered around — no
+hash, no second key component — because it does not occur in measured data:
+zero occurrences of `[` or `]` in `_wp_attached_file` on the production site
+surveyed for this ADR, and WordPress itself runs uploads through
+`sanitize_file_name()` at the point of upload, so a stored value is normally
+already sanitized before this code ever sees it.
+
 A note on how this decision was reached, because it is the point of the
 practice rather than a detail of it: the first version of this ADR added only
 the directory, and seven review rounds passed it. The same-directory half was
@@ -103,7 +126,10 @@ source — recovering that association is exactly what the old layout destroyed.
 Those files are reported and left alone; the new path is empty for them, so they
 are re-encoded on first view. The command moves rather than copies (no transient
 doubling of the cache), and is idempotent, so an interrupted run is resumed by
-running it again.
+running it again — including for a root upload, whose migrated derivative
+lands at the same depth in the size directory as an unmigrated legacy one, and
+so is told apart from it by matching against the source's own full name rather
+than by where it sits in the tree.
 
 The added segment is derived from a URL, so it inherits the path-traversal
 duty that `sanitize_file_name()` already discharges for the filename. That