fix: waive reviewed cleanup recency guard (#888) (#889)

Co-authored-by: homeboy-ci[bot] <266378653+homeboy-ci[bot]@users.noreply.github.com>

Author: chubes4

inc/Workspace/WorkspaceWorktreeCleanupEngine.php

@@ -1368,7 +1368,8 @@ private function apply_worktree_cleanup_plan_candidates( array $candidates, bool
 
 		foreach ( $candidates as $candidate ) {
 			++$processed;
-			$revalidated = $this->revalidate_bounded_cleanup_eligible_candidate($candidate, $force, $stale_liveness_only, $discard_unpushed);
+			$reviewed_lifecycle_snapshot = is_array($candidate['metadata'] ?? null) ? $candidate['metadata'] : array();
+			$revalidated                 = $this->revalidate_bounded_cleanup_eligible_candidate($candidate, $force, $stale_liveness_only, $discard_unpushed, $reviewed_lifecycle_snapshot);
 			if ( isset($revalidated['skipped']) ) {
 				$skipped[] = $revalidated['skipped'];
 				continue;
@@ -1461,15 +1462,22 @@ function () use ( $repo, $branch, $wt_path, $force, $remove_timeout_seconds ) {
 	 *
 	 * @param  array $candidate Inventory candidate row.
 	 * @param  bool  $force     Allow dirty worktrees.
-		 * @return array<string,mixed>
-		 */
-	private function revalidate_bounded_cleanup_eligible_candidate( array $candidate, bool $force, bool $stale_liveness_only = false, bool $discard_unpushed = false ): array {
+	 * @param  bool  $stale_liveness_only Limit removal to stale worktrees.
+	 * @param  bool  $discard_unpushed     Allow removal of reviewed unpushed commits.
+	 * @param  array<string,mixed>|null $reviewed_lifecycle_snapshot Lifecycle metadata captured in a reviewed plan.
+	 * @return array<string,mixed>
+	 */
+	private function revalidate_bounded_cleanup_eligible_candidate( array $candidate, bool $force, bool $stale_liveness_only = false, bool $discard_unpushed = false, ?array $reviewed_lifecycle_snapshot = null ): array {
 		$handle   = (string) ( $candidate['handle'] ?? '' );
 		$repo     = (string) ( $candidate['repo'] ?? '' );
 		$branch   = (string) ( $candidate['branch'] ?? '' );
 		$wt_path  = (string) ( $candidate['path'] ?? '' );
 		$liveness = (string) ( $candidate['liveness'] ?? '' );
 		$metadata = is_array($candidate['metadata'] ?? null) ? $candidate['metadata'] : array();
+		if ( null !== $reviewed_lifecycle_snapshot && function_exists('get_option') ) {
+			$current_metadata = WorktreeContextInjector::get_metadata($handle);
+			$metadata         = is_array($current_metadata) ? $current_metadata : array();
+		}
 
 		if ( $stale_liveness_only && 'stale' !== $liveness ) {
 			return array(
@@ -1513,7 +1521,7 @@ private function revalidate_bounded_cleanup_eligible_candidate( array $candidate
 		}
 
 		$recent_activity = $this->worktree_cleanup_recent_activity_protection($metadata);
-		if ( null !== $recent_activity ) {
+		if ( null !== $recent_activity && ( null === $reviewed_lifecycle_snapshot || ! $this->worktree_cleanup_lifecycle_matches_reviewed_plan($reviewed_lifecycle_snapshot, $metadata) ) ) {
 			return array(
 				'skipped' => array_merge(
 					array(
@@ -1834,6 +1842,23 @@ private function worktree_cleanup_recent_activity_protection( array $metadata ):
 		);
 	}
 
+	/**
+	 * Determine whether a reviewed row still has the lifecycle state the operator saw.
+	 *
+	 * @param  array<string,mixed> $reviewed_metadata Lifecycle metadata captured in the reviewed plan.
+	 * @param  array<string,mixed> $current_metadata  Current lifecycle metadata.
+	 * @return bool
+	 */
+	private function worktree_cleanup_lifecycle_matches_reviewed_plan( array $reviewed_metadata, array $current_metadata ): bool {
+		foreach ( array( 'finalized_at', 'cleanup_eligible_at', 'created_at', 'lifecycle_state' ) as $field ) {
+			if ( (string) ( $reviewed_metadata[ $field ] ?? '' ) !== (string) ( $current_metadata[ $field ] ?? '' ) ) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
 	/**
 	 * Fail-safe open-PR protection for remote-tracking-clean cleanup rows.
 	 *

tests/worktree-retention-apply-protections.php

@@ -105,6 +105,11 @@ public function revalidate( array $candidate ): array {
 			return $method->invoke($this, $candidate, false, false, false);
 		}
 
+		public function revalidate_reviewed( array $candidate, array $reviewed_lifecycle_snapshot ): array {
+			$method = new ReflectionMethod($this, 'revalidate_bounded_cleanup_eligible_candidate');
+			return $method->invoke($this, $candidate, false, false, false, $reviewed_lifecycle_snapshot);
+		}
+
 		private function validate_containment( string $path, string $container ): array {
 			$real_path  = realpath($path);
 			$real_root  = realpath($container);
@@ -173,6 +178,16 @@ private function git_get_remote( string $path ): ?string {
 	retention_apply_protections_assert('recent_activity' === ( $recent_lifecycle['skipped']['reason_code'] ?? null ), 'recent cleanup_eligible_at rows are protected from apply removal');
 	retention_apply_protections_assert('cleanup_eligible_at' === ( $recent_lifecycle['skipped']['activity_field'] ?? null ), 'recent lifecycle protection identifies the lifecycle activity field');
 
+	$reviewed_lifecycle_candidate                                      = $base_candidate;
+	$reviewed_lifecycle_candidate['metadata']['cleanup_eligible_at'] = gmdate('c', time() - 60);
+	$reviewed_lifecycle                                              = $harness->revalidate_reviewed($reviewed_lifecycle_candidate, $reviewed_lifecycle_candidate['metadata']);
+	retention_apply_protections_assert(! isset($reviewed_lifecycle['skipped']), 'reviewed rows with unchanged recent lifecycle metadata remain removable');
+
+	$changed_lifecycle_candidate                               = $reviewed_lifecycle_candidate;
+	$changed_lifecycle_candidate['metadata']['finalized_at'] = gmdate('c', time() - 30);
+	$changed_lifecycle                                        = $harness->revalidate_reviewed($changed_lifecycle_candidate, $reviewed_lifecycle_candidate['metadata']);
+	retention_apply_protections_assert('recent_activity' === ( $changed_lifecycle['skipped']['reason_code'] ?? null ), 'reviewed rows with changed lifecycle metadata remain protected');
+
 	GitHubAbilities::$mode = 'open';
 	$open_pr              = $harness->revalidate($base_candidate);
 	retention_apply_protections_assert('open_pr' === ( $open_pr['skipped']['reason_code'] ?? null ), 'open PR heads are protected from apply removal');