Explain hygiene cleanup revalidation blockers

Author: homeboy-ci[bot]

inc/Cli/Commands/WorkspaceCommand.php

@@ -5109,14 +5109,18 @@ private function render_workspace_hygiene_report( array $report, array $assoc_ar
 			$this->format_items(
 				array_map(
 					fn( $row ) => array(
-						'handle' => $row['handle'] ?? '',
-						'branch' => $row['branch'] ?? '',
-						'signal' => $row['signal'] ?? '',
-						'size'   => $row['size_human'] ?? '',
+						'handle'         => $row['handle'] ?? '',
+						'branch'         => $row['branch'] ?? '',
+						'signal'         => $row['signal'] ?? '',
+						'size'           => $row['size_human'] ?? '',
+						'dirty'          => array_key_exists('dirty', (array) $row) ? ( null === $row['dirty'] ? 'unknown' : $row['dirty'] ) : '',
+						'unpushed'       => array_key_exists('unpushed', (array) $row) ? ( null === $row['unpushed'] ? 'unknown' : $row['unpushed'] ) : '',
+						'fresh_status'   => $row['fresh_revalidation_status'] ?? '',
+						'fresh_blockers' => implode(',', array_map('strval', (array) ( $row['fresh_revalidation_blockers'] ?? array() ))),
 					),
 					$candidates
 				),
-				array( 'handle', 'branch', 'signal', 'size' ),
+				array( 'handle', 'branch', 'signal', 'size', 'dirty', 'unpushed', 'fresh_status', 'fresh_blockers' ),
 				array( 'format' => 'table' ),
 				'handle'
 			);
@@ -5126,6 +5130,9 @@ private function render_workspace_hygiene_report( array $report, array $assoc_ar
 			WP_CLI::log('');
 			WP_CLI::log('Suggested cleanup review:');
 			WP_CLI::log( (string) $report['suggested_cleanup_command']);
+			if ( ! empty($cleanup['expected_outcome']) ) {
+				WP_CLI::log( (string) $cleanup['expected_outcome']);
+			}
 		}
 
 		if ( ! empty($report['suggested_size_command']) ) {

inc/Cli/WorkspaceCompactOutput.php

@@ -95,6 +95,7 @@ public static function hygiene_report( array $report ): array {
 				'cleanup'                   => array(
 					'blocker_probe_source' => $cleanup['blocker_probe_source'] ?? null,
 					'blocker_counts'       => $cleanup['blocker_counts'] ?? null,
+					'expected_outcome'     => $cleanup['expected_outcome'] ?? null,
 					'summary'              => (array) ( $cleanup['summary'] ?? array() ),
 					'biggest_candidates'   => self::compact_rows( (array) ( $cleanup['biggest_candidates'] ?? array() ) ),
 				),
@@ -311,12 +312,12 @@ private static function compact_row( array $row ): array {
 			'path'        => $row['path'] ?? null,
 			'pr_url'      => $row['pr_url'] ?? null,
 		);
-		foreach ( array( 'size_bytes', 'artifact_size_bytes', 'bytes_reclaimed', 'dirty', 'unpushed', 'age_days', 'created_at', 'liveness' ) as $field ) {
+		foreach ( array( 'size_bytes', 'artifact_size_bytes', 'bytes_reclaimed', 'dirty', 'unpushed', 'age_days', 'created_at', 'liveness', 'fresh_revalidation_status' ) as $field ) {
 			if ( array_key_exists( $field, $row ) ) {
 				$compact[ $field ] = $row[ $field ];
 			}
 		}
-		foreach ( array( 'size_status', 'size_accounting', 'fields_skipped' ) as $field ) {
+		foreach ( array( 'size_status', 'size_accounting', 'fields_skipped', 'fresh_revalidation_blockers', 'fresh_revalidation_checks' ) as $field ) {
 			if ( array_key_exists( $field, $row ) ) {
 				$compact[ $field ] = $row[ $field ];
 			}

inc/Workspace/WorkspaceHygieneReport.php

@@ -724,6 +724,7 @@ private function summarize_workspace_cleanup( ?array $cleanup, ?array $error, ar
 		$summary        = (array) ( $cleanup['summary'] ?? array() );
 		$skipped_reason = (array) ( $summary['skipped_by_reason'] ?? array() );
 		$probe_source   = ! empty($cleanup['inventory_only']) ? 'inventory_known' : 'fresh_probe';
+		$candidates     = $this->annotate_workspace_cleanup_candidates_for_hygiene($candidates, $probe_source);
 		$empty_blockers = array(
 			'dirty_worktree'   => 0,
 			'unpushed_commits' => 0,
@@ -736,7 +737,7 @@ private function summarize_workspace_cleanup( ?array $cleanup, ?array $error, ar
 			'dirty_worktree'   => (int) ( $skipped_reason['dirty_worktree'] ?? 0 ),
 			'unpushed_commits' => (int) ( $skipped_reason['unpushed_commits'] ?? 0 ),
 		);
-		return array(
+		$result = array(
 			'included'             => true,
 			'dry_run'              => true,
 			'skip_github'          => true,
@@ -748,6 +749,58 @@ private function summarize_workspace_cleanup( ?array $cleanup, ?array $error, ar
 			'skipped_by_reason'    => $skipped_reason,
 			'candidates_by_signal' => $summary['candidates_by_signal'] ?? array(),
 		);
+
+		$expected_outcome = $this->workspace_cleanup_expected_outcome($summary, ! empty($cleanup['inventory_only']));
+		if ( '' !== $expected_outcome ) {
+			$result['expected_outcome'] = $expected_outcome;
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Add concise fresh-revalidation context to cleanup candidate examples.
+	 *
+	 * @param  array<int,array<string,mixed>> $candidates Candidate rows.
+	 * @param  string                         $probe_source inventory_known|fresh_probe.
+	 * @return array<int,array<string,mixed>>
+	 */
+	private function annotate_workspace_cleanup_candidates_for_hygiene( array $candidates, string $probe_source ): array {
+		foreach ( $candidates as &$candidate ) {
+			if ( 'inventory_known' === $probe_source ) {
+				$candidate['fresh_revalidation_status']  = (string) ( $candidate['safety_probe_status'] ?? 'not_run_inventory_only' );
+				$candidate['fresh_revalidation_blockers'] = array( 'pending_fresh_revalidation' );
+				$candidate['fresh_revalidation_checks']   = array( 'dirty_worktree', 'unpushed_commits', 'primary_or_protected_worktree', 'containment_failure' );
+				continue;
+			}
+
+			$candidate['fresh_revalidation_status'] = 'passed';
+			if ( ! array_key_exists('unpushed', $candidate) ) {
+				$candidate['unpushed'] = 0;
+			}
+		}
+		unset($candidate);
+
+		return $candidates;
+	}
+
+	/**
+	 * Explain what the suggested cleanup/apply path can do when hygiene has no fresh-safe rows.
+	 *
+	 * @param  array<string,mixed> $summary        Cleanup summary.
+	 * @param  bool                $inventory_only Whether hygiene used inventory-only cleanup.
+	 */
+	private function workspace_cleanup_expected_outcome( array $summary, bool $inventory_only ): string {
+		$fresh_safe = (int) ( $summary['fresh_safe_removable_count'] ?? 0 );
+		$pending    = (int) ( $summary['cleanup_buckets'][ WorktreeCleanupClassifier::BUCKET_CLEANUP_ELIGIBLE_UNPROBED ] ?? 0 );
+		if ( ! $inventory_only || $fresh_safe > 0 || $pending <= 0 ) {
+			return '';
+		}
+
+		return sprintf(
+			'Expected outcome: hygiene found %d cleanup-eligible row(s) pending fresh revalidation and 0 fresh-safe removals. The bounded apply path will remove only rows that still pass dirty, unpushed, primary/protected, and containment checks; blockers are skipped with fresh reason codes.',
+			$pending
+		);
 	}
 
 	/**

inc/Workspace/WorktreeCleanupCandidateClassifier.php

@@ -92,6 +92,7 @@ public static function classify_merge_signal_path( array $context, ?array $signa
 			$base,
 			array(
 				'dirty'           => (int) ( $context['dirty_count'] ?? 0 ),
+				'unpushed'        => 0,
 				'cleanup_reasons' => array_values(array_filter(array( $signal['signal'] ?? '', $signal['reason'] ?? '' ))),
 				'liveness'        => (string) ( $context['liveness'] ?? '' ),
 			),

tests/workspace-compact-output.php

@@ -38,6 +38,11 @@ function compact_output_large_rows( int $count ): array {
 }
 
 $large_rows = compact_output_large_rows(40);
+$hygiene_candidate_rows = $large_rows;
+$hygiene_candidate_rows[0]['dirty']                        = null;
+$hygiene_candidate_rows[0]['fresh_revalidation_status']    = 'not_run_inventory_only';
+$hygiene_candidate_rows[0]['fresh_revalidation_blockers']  = array( 'pending_fresh_revalidation' );
+$hygiene_candidate_rows[0]['fresh_revalidation_checks']    = array( 'dirty_worktree', 'unpushed_commits', 'primary_or_protected_worktree', 'containment_failure' );
 $cleanup    = WorkspaceCompactOutput::cleanup_result(
 	array(
 		'success'    => true,
@@ -218,6 +223,7 @@ function compact_output_large_rows( int $count ): array {
 		'locks'                     => array( 'active' => 2, 'stale' => 40, 'database' => array( 'locks' => $large_rows ) ),
 		'cleanup'                   => array(
 			'blocker_probe_source' => 'inventory_known',
+			'expected_outcome'     => 'Expected outcome: hygiene found 40 cleanup-eligible row(s) pending fresh revalidation and 0 fresh-safe removals.',
 			'blocker_counts'       => array(
 				'inventory_known' => array(
 					'dirty_worktree'   => 3,
@@ -238,7 +244,7 @@ function compact_output_large_rows( int $count ): array {
 					'safe_to_remove_now'                    => 0,
 				),
 			),
-			'biggest_candidates' => $large_rows,
+			'biggest_candidates' => $hygiene_candidate_rows,
 		),
 		'size'                      => array(
 			'total_bytes' => 123456,
@@ -263,10 +269,14 @@ function compact_output_large_rows( int $count ): array {
 compact_output_assert('inventory_known' === ( $hygiene['cleanup']['blocker_probe_source'] ?? null ), 'Compact hygiene output must expose blocker probe source.');
 compact_output_assert(3 === ( $hygiene['cleanup']['blocker_counts']['inventory_known']['dirty_worktree'] ?? null ), 'Compact hygiene output must preserve inventory-known dirty blocker bucket.');
 compact_output_assert(0 === ( $hygiene['cleanup']['blocker_counts']['fresh_probe']['dirty_worktree'] ?? null ), 'Compact hygiene output must preserve fresh-probed dirty blocker bucket.');
+compact_output_assert(isset($hygiene['cleanup']['expected_outcome']), 'Compact hygiene output must preserve expected cleanup outcome.');
 compact_output_assert(40 === ( $hygiene['cleanup']['summary']['cleanup_buckets']['cleanup_eligible_pending_revalidation'] ?? null ), 'Compact cleanup summary must preserve pending-revalidation bucket.');
 compact_output_assert(0 === ( $hygiene['cleanup']['summary']['cleanup_buckets']['safe_to_remove_now'] ?? null ), 'Compact cleanup summary must not mark unprobed inventory candidates safe.');
 compact_output_assert(123456 === ( $hygiene['size']['total_bytes'] ?? null ), 'Compact hygiene output must preserve size bytes.');
 compact_output_assert(40 === ( $hygiene['size']['entry_count'] ?? null ), 'Compact hygiene output must preserve size entry count.');
 compact_output_assert(count((array) ( $hygiene['cleanup']['biggest_candidates'] ?? array() )) <= 5, 'Compact hygiene output must sample cleanup candidates.');
+compact_output_assert('not_run_inventory_only' === ( $hygiene['cleanup']['biggest_candidates'][0]['fresh_revalidation_status'] ?? null ), 'Compact hygiene candidates must preserve fresh revalidation status.');
+compact_output_assert(array( 'pending_fresh_revalidation' ) === ( $hygiene['cleanup']['biggest_candidates'][0]['fresh_revalidation_blockers'] ?? null ), 'Compact hygiene candidates must preserve fresh blocker examples.');
+compact_output_assert(in_array('unpushed_commits', (array) ( $hygiene['cleanup']['biggest_candidates'][0]['fresh_revalidation_checks'] ?? array() ), true), 'Compact hygiene candidates must preserve fresh revalidation checks.');
 
 echo "workspace compact output test passed.\n";

tests/workspace-hygiene-cleanup-summary.php

@@ -0,0 +1,77 @@
+<?php
+/**
+ * Focused coverage for hygiene cleanup candidate fresh-revalidation context.
+ */
+
+declare(strict_types=1);
+
+if ( ! defined('ABSPATH') ) {
+	define('ABSPATH', __DIR__ . '/fixtures/');
+}
+
+require_once dirname(__DIR__) . '/inc/Workspace/WorktreeCleanupClassifier.php';
+require_once dirname(__DIR__) . '/inc/Workspace/WorkspaceHygieneReport.php';
+
+function hygiene_cleanup_summary_assert( bool $condition, string $message ): void {
+	if ( ! $condition ) {
+		throw new RuntimeException($message);
+	}
+}
+
+$hygiene = new class {
+	use DataMachineCode\Workspace\WorkspaceHygieneReport;
+
+	public function annotate( array $candidates, string $source ): array {
+		$method = new ReflectionMethod($this, 'annotate_workspace_cleanup_candidates_for_hygiene');
+		return $method->invoke($this, $candidates, $source);
+	}
+
+	public function outcome( array $summary, bool $inventory_only ): string {
+		$method = new ReflectionMethod($this, 'workspace_cleanup_expected_outcome');
+		return $method->invoke($this, $summary, $inventory_only);
+	}
+};
+
+$inventory_candidates = $hygiene->annotate(
+	array(
+		array(
+			'handle'              => 'repo@cleanup-eligible',
+			'safety_probe_status' => 'not_run_inventory_only',
+			'dirty'               => null,
+		),
+	),
+	'inventory_known'
+);
+
+hygiene_cleanup_summary_assert('not_run_inventory_only' === $inventory_candidates[0]['fresh_revalidation_status'], 'inventory candidates explain that fresh probes have not run');
+hygiene_cleanup_summary_assert(array( 'pending_fresh_revalidation' ) === $inventory_candidates[0]['fresh_revalidation_blockers'], 'inventory candidates expose pending fresh blocker');
+hygiene_cleanup_summary_assert(in_array('dirty_worktree', $inventory_candidates[0]['fresh_revalidation_checks'], true), 'inventory candidates list dirty revalidation check');
+hygiene_cleanup_summary_assert(in_array('unpushed_commits', $inventory_candidates[0]['fresh_revalidation_checks'], true), 'inventory candidates list unpushed revalidation check');
+
+$fresh_candidates = $hygiene->annotate(
+	array(
+		array(
+			'handle' => 'repo@safe',
+			'dirty'  => 0,
+		),
+	),
+	'fresh_probe'
+);
+
+hygiene_cleanup_summary_assert('passed' === $fresh_candidates[0]['fresh_revalidation_status'], 'fresh-probed candidates are marked passed');
+hygiene_cleanup_summary_assert(0 === $fresh_candidates[0]['unpushed'], 'fresh-probed candidates expose passed unpushed check');
+
+$expected_outcome = $hygiene->outcome(
+	array(
+		'fresh_safe_removable_count' => 0,
+		'cleanup_buckets'            => array(
+			DataMachineCode\Workspace\WorktreeCleanupClassifier::BUCKET_CLEANUP_ELIGIBLE_UNPROBED => 8,
+		),
+	),
+	true
+);
+
+hygiene_cleanup_summary_assert(str_contains($expected_outcome, '8 cleanup-eligible row(s) pending fresh revalidation'), 'expected outcome names pending cleanup-eligible rows');
+hygiene_cleanup_summary_assert(str_contains($expected_outcome, '0 fresh-safe removals'), 'expected outcome names zero fresh-safe removals');
+
+echo "workspace hygiene cleanup summary test passed.\n";

tests/worktree-cleanup-candidate-classifier.php

@@ -54,6 +54,7 @@ function () use ( &$evidence_called ): array {
 worktree_cleanup_candidate_assert_same('candidate', $candidate_result['type'], 'merged signal is a candidate');
 worktree_cleanup_candidate_assert_same('github-merged-pr', $candidate_result['row']['signal'], 'candidate signal is preserved');
 worktree_cleanup_candidate_assert_same('github-merged-pr', $candidate_result['row']['reason_code'], 'candidate reason_code matches signal');
+worktree_cleanup_candidate_assert_same(0, $candidate_result['row']['unpushed'], 'fresh safe candidate records the passed unpushed probe');
 worktree_cleanup_candidate_assert_same(false, $evidence_called, 'no-signal evidence stays lazy for candidates');
 
 $no_signal_filter = null;