Commit 670b037e05d for woocommerce

commit 670b037e05d43f6236a98ddffae81d8741bcf80c
Author: AnnaMag <AnnaMag@users.noreply.github.com>
Date:   Thu Nov 19 13:18:19 2026 +0100

    Agent readiness: list whether llms.txt holds WooCommerce's store guidance (#70909)

    * Agent readiness: list whether llms.txt holds WooCommerce's store guidance

    With WooCommerce's llms.txt fallback (#70741), the declared-to-agents block
    lists whether the served llms.txt, from WooCommerce or another provider, holds
    WooCommerce's guidance (Store API, UCP, policies). Information only; not listed
    without the fallback.

    * Agent readiness: mark the llms.txt guidance changelog as dev-only

diff --git a/plugins/woocommerce/changelog/add-agent-readiness-llms-txt-guidance b/plugins/woocommerce/changelog/add-agent-readiness-llms-txt-guidance
new file mode 100644
index 00000000000..ee8f2f70b65
--- /dev/null
+++ b/plugins/woocommerce/changelog/add-agent-readiness-llms-txt-guidance
@@ -0,0 +1,3 @@
+Significance: patch
+Type: dev
+Comment: Agent readiness: list whether the served llms.txt holds WooCommerce's store guidance; nothing ships to merchants.
diff --git a/plugins/woocommerce/changelog/fix-agent-readiness-llms-guidance-checks b/plugins/woocommerce/changelog/fix-agent-readiness-llms-guidance-checks
new file mode 100644
index 00000000000..b7164768df7
--- /dev/null
+++ b/plugins/woocommerce/changelog/fix-agent-readiness-llms-guidance-checks
@@ -0,0 +1,4 @@
+Significance: patch
+Type: fix
+
+Treat a rate-limited or truncated llms.txt read as couldn't check, not missing.
diff --git a/plugins/woocommerce/src/Internal/AgentReadiness/DeclaredToAgents.php b/plugins/woocommerce/src/Internal/AgentReadiness/DeclaredToAgents.php
index 96289703f62..45c32145e66 100644
--- a/plugins/woocommerce/src/Internal/AgentReadiness/DeclaredToAgents.php
+++ b/plugins/woocommerce/src/Internal/AgentReadiness/DeclaredToAgents.php
@@ -60,9 +60,47 @@ class DeclaredToAgents {
 				'found' => $line[1],
 			);
 		}
+		$status = $this->llms_txt_status();
+		// In a subdirectory WooCommerce serves llms.txt under the home path, not at the host root read here.
+		if ( null !== $status && '' !== trim( $status['section'] ) && '' === trim( (string) wp_parse_url( home_url(), PHP_URL_PATH ), '/' ) ) {
+			$items[] = array(
+				'id'    => 'llms-txt-woocommerce-guidance',
+				'name'  => __( 'WooCommerce’s store guidance in llms.txt (Store API, UCP, policies)', 'woocommerce' ),
+				'found' => self::has_guidance( $responses, $status['section'] ),
+			);
+		}
 		return $items;
 	}

+	/**
+	 * WooCommerce's llms.txt status, null without its llms.txt fallback (woocommerce #70741).
+	 *
+	 * @return array{status:string,section:string}|null
+	 */
+	protected function llms_txt_status(): ?array {
+		return StoreOutputChecks::core_llms_txt_status();
+	}
+
+	/**
+	 * Whether the served llms.txt, from WooCommerce or any other provider, holds WooCommerce's guidance.
+	 * Null when the file couldn't be checked (refused, rate-limited, or truncated before a match).
+	 *
+	 * @param StoreResponses $responses Responses of the scan.
+	 * @param string         $section   Guidance WooCommerce adds.
+	 */
+	private static function has_guidance( StoreResponses $responses, string $section ): ?bool {
+		$served = self::file_served( $responses, '/llms.txt' );
+		if ( true !== $served ) {
+			return $served;
+		}
+		$response = $responses->get( StoreOutputChecks::host_root( '/llms.txt' ) );
+		$body     = (string) ( $response['body'] ?? '' );
+		if ( StoreOutputChecks::has_llms_txt_guidance( $body, $section ) ) {
+			return true;
+		}
+		return ! empty( $response['truncated'] ) ? null : false;
+	}
+
 	/**
 	 * Items served as a file at a known path, by id.
 	 *
@@ -278,6 +316,7 @@ class DeclaredToAgents {
 	/**
 	 * Whether a path answers with a text file. A theme that answers every URL with a page, or a host
 	 * that answers unknown paths with a 200 JSON or HTML error, has no such file.
+	 * Null when a 200 body was cut off before any content, so a blank prefix is not a missing file.
 	 *
 	 * @param StoreResponses $responses Store responses.
 	 * @param string         $path      Path from the host root.
@@ -288,6 +327,10 @@ class DeclaredToAgents {
 			return null;
 		}
 		$body = ltrim( $response['body'], " \t\r\n\xEF\xBB\xBF" );
+		// Only a 200 can be a file that was cut off before content; a truncated 404 stays missing.
+		if ( 200 === $response['status'] && '' === $body && ! empty( $response['truncated'] ) ) {
+			return null;
+		}
 		return 200 === $response['status'] && '' !== $body && '<' !== $body[0]
 			&& 0 !== stripos( $response['headers']['content-type'] ?? '', 'text/html' )
 			&& null === json_decode( $body );
diff --git a/plugins/woocommerce/src/Internal/AgentReadiness/ReadinessCheckPage.php b/plugins/woocommerce/src/Internal/AgentReadiness/ReadinessCheckPage.php
index be9c10435ee..8dbe73ec8a8 100644
--- a/plugins/woocommerce/src/Internal/AgentReadiness/ReadinessCheckPage.php
+++ b/plugins/woocommerce/src/Internal/AgentReadiness/ReadinessCheckPage.php
@@ -898,15 +898,24 @@ class ReadinessCheckPage implements RegisterHooksInterface {
 			return null;
 		}
 		$found = array_filter( $items, static fn( array $item ): bool => true === ( $item['found'] ?? null ) );
+		$text  = sprintf(
+			/* translators: %s: how many items were found, such as "Found 4 of 33". */
+			__( 'Optional files that some AI assistants look for. You don’t need to fix anything. %s.', 'woocommerce' ),
+			/* translators: 1: number of items found, 2: number of items looked for. */
+			sprintf( __( 'Found %1$s of %2$s', 'woocommerce' ), number_format_i18n( count( $found ) ), number_format_i18n( count( $items ) ) )
+		);
+		// Served llms.txt caches guidance for a few minutes for anonymous requests, so a fresh
+		// policy/MCP/UCP change can briefly look missing until that cache expires.
+		foreach ( $items as $item ) {
+			if ( 'llms-txt-woocommerce-guidance' === ( $item['id'] ?? '' ) && false === ( $item['found'] ?? null ) ) {
+				$text .= ' ' . __( 'If you just changed policy pages, MCP, or UCP, wait a few minutes and check again. WooCommerce caches its llms.txt briefly.', 'woocommerce' );
+				break;
+			}
+		}
 		return array(
 			'title' => __( 'What does your store share with AI assistants?', 'woocommerce' ),
 			'badge' => self::badge_data( array( 'off', __( 'Optional', 'woocommerce' ) ) ),
-			'text'  => sprintf(
-				/* translators: %s: how many items were found, such as "Found 4 of 33". */
-				__( 'Optional files that some AI assistants look for. You don’t need to fix anything. %s.', 'woocommerce' ),
-				/* translators: 1: number of items found, 2: number of items looked for. */
-				sprintf( __( 'Found %1$s of %2$s', 'woocommerce' ), number_format_i18n( count( $found ) ), number_format_i18n( count( $items ) ) )
-			),
+			'text'  => $text,
 			'items' => array_map(
 				static fn( array $item ): array => array(
 					'name'  => (string) ( $item['name'] ?? '' ),
diff --git a/plugins/woocommerce/src/Internal/AgentReadiness/StoreOutputChecks.php b/plugins/woocommerce/src/Internal/AgentReadiness/StoreOutputChecks.php
index dbe29d2bdf3..b48b46c0955 100644
--- a/plugins/woocommerce/src/Internal/AgentReadiness/StoreOutputChecks.php
+++ b/plugins/woocommerce/src/Internal/AgentReadiness/StoreOutputChecks.php
@@ -5,6 +5,7 @@ namespace Automattic\WooCommerce\Internal\AgentReadiness;

 use Automattic\WooCommerce\Enums\ProductStatus;
 use Automattic\WooCommerce\Internal\ComingSoon\ComingSoonHelper;
+use Automattic\WooCommerce\Internal\LlmsTxt\LlmsTxt;
 use Automattic\WooCommerce\StoreApi\Utilities\Ucp\Utils as UcpUtils;

 defined( 'ABSPATH' ) || exit;
@@ -893,6 +894,35 @@ class StoreOutputChecks {
 		return (bool) $test( $body );
 	}

+	/**
+	 * Whether a served llms.txt holds WooCommerce's guidance, as WooCommerce's own file does.
+	 * Line endings are normalized so a CRLF copy of the section still matches.
+	 *
+	 * @param string $body    Served llms.txt.
+	 * @param string $section Guidance WooCommerce adds, '' when it adds none.
+	 */
+	public static function has_llms_txt_guidance( string $body, string $section ): bool {
+		$section = trim( str_replace( "\r\n", "\n", $section ) );
+		$body    = str_replace( "\r\n", "\n", $body );
+		return '' !== $section && str_contains( $body, $section );
+	}
+
+	/**
+	 * WooCommerce's llms.txt status: disabled, physical_file or unknown, with the guidance it adds.
+	 * Null when reading status fails.
+	 *
+	 * @return array{status:string,section:string}|null
+	 */
+	public static function core_llms_txt_status(): ?array {
+		try {
+			$status = wc_get_container()->get( LlmsTxt::class )->get_status();
+		} catch ( \Throwable $e ) {
+			wc_get_logger()->warning( 'Agent readiness could not read the llms.txt status: ' . $e->getMessage(), array( 'source' => 'agent-readiness' ) );
+			return null;
+		}
+		return is_string( $status['status'] ?? null ) && is_string( $status['section'] ?? null ) ? $status : null;
+	}
+
 	/**
 	 * Whether the first few links in llms.txt to the store's own pages open. Links to other sites
 	 * aren't loaded. Null when one couldn't be loaded and none was broken.
@@ -930,15 +960,15 @@ class StoreOutputChecks {

 	/**
 	 * Whether a status says the store's request to itself was refused or failed, not that the
-	 * page is missing: a server error, or a firewall or security plugin answering 401 or 403.
-	 * A check then reports couldn't check, as it does when the page times out.
+	 * page is missing: a server error, rate limit (429), or a firewall or security plugin
+	 * answering 401 or 403. A check then reports couldn't check, as it does when the page times out.
 	 *
 	 * @since 11.4.0
 	 *
 	 * @param int $status HTTP status.
 	 */
 	public static function blocked( int $status ): bool {
-		return $status >= 500 || in_array( $status, array( 401, 403 ), true );
+		return $status >= 500 || in_array( $status, array( 401, 403, 429 ), true );
 	}

 	/**
diff --git a/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/AgenticCommerceSettingsTest.php b/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/AgenticCommerceSettingsTest.php
index 1a9bf40158e..317e55bdf1b 100644
--- a/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/AgenticCommerceSettingsTest.php
+++ b/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/AgenticCommerceSettingsTest.php
@@ -634,6 +634,21 @@ class AgenticCommerceSettingsTest extends WC_Unit_Test_Case {
 			$view['declared']['items'],
 			'Every item, found or not'
 		);
+
+		$report             = get_option( 'woocommerce_agent_readiness_report' );
+		$report['declared'] = array(
+			array(
+				'id'    => 'llms-txt-woocommerce-guidance',
+				'name'  => 'WooCommerce store guidance',
+				'found' => false,
+			),
+		);
+		update_option( 'woocommerce_agent_readiness_report', $report );
+		$this->assertStringContainsString(
+			'WooCommerce caches its llms.txt briefly',
+			$this->view()['declared']['text'],
+			'Missing WooCommerce guidance notes the short llms.txt cache'
+		);
 		$this->assertSame(
 			array(
 				'intent' => 'none',
diff --git a/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/DeclaredToAgentsTest.php b/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/DeclaredToAgentsTest.php
index 675b0f5c96b..9da89e1cf77 100644
--- a/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/DeclaredToAgentsTest.php
+++ b/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/DeclaredToAgentsTest.php
@@ -63,19 +63,21 @@ class DeclaredToAgentsTest extends WC_Unit_Test_Case {
 	}

 	/**
-	 * @testdox A 401 or 403 is not checked: a firewall can refuse a file that exists.
+	 * @testdox A 401, 403 or 429 is not checked: a firewall or rate limit can refuse a file that exists.
 	 */
 	public function test_blocked_response_is_not_checked(): void {
 		$results = $this->results(
 			array(
 				'/ai.txt'                      => array( 403, 'Forbidden' ),
 				'/.well-known/agent-card.json' => array( 401, '' ),
+				'/llms-full.txt'               => array( 429, 'Too Many Requests' ),
 				'markdown /'                   => array( 403, '' ),
 			)
 		);

 		$this->assertNull( $results['ai-txt'] );
 		$this->assertNull( $results['a2a-agent-card'] );
+		$this->assertNull( $results['llms-full'] );
 		$this->assertNull( $results['markdown-pages'] );
 	}

@@ -85,17 +87,25 @@ class DeclaredToAgentsTest extends WC_Unit_Test_Case {
 	public function test_files(): void {
 		$results = $this->results(
 			array(
-				'/ai.txt'                  => array( 200, 'User-Agent: *' ),
-				'/.well-known/agents.json' => array( 200, '<!doctype html><html></html>' ),
-				'/AGENTS.md'               => array( 200, '{"code":"not_found","message":"No route"}' ),
-				'/auth.md'                 => array( 200, 'Not found', array( 'content-type' => 'text/html; charset=UTF-8' ) ),
-				'/sitemap.md'              => array( 200, "\xEF\xBB\xBF<!doctype html><html></html>" ),
+				'/ai.txt'                   => array( 200, 'User-Agent: *' ),
+				'/.well-known/agents.json'  => array( 200, '<!doctype html><html></html>' ),
+				'/AGENTS.md'                => array( 200, '{"code":"not_found","message":"No route"}' ),
+				'/auth.md'                  => array( 200, 'Not found', array( 'content-type' => 'text/html; charset=UTF-8' ) ),
+				'/sitemap.md'               => array( 200, "\xEF\xBB\xBF<!doctype html><html></html>" ),
+				'/.well-known/security.txt' => array(
+					404,
+					"\n\n",
+					array(
+						'content-type'   => 'text/plain',
+						'content-length' => '999999',
+					),
+				),
 			)
 		);

 		$this->assertTrue( $results['ai-txt'] );
 		$this->assertFalse( $results['agents-json'], 'A page is not a JSON document' );
-		$this->assertFalse( $results['security-txt'], 'A 404' );
+		$this->assertFalse( $results['security-txt'], 'A truncated 404 is still missing' );
 		$this->assertFalse( $results['agents-md'], 'A 200 JSON error is not a file' );
 		$this->assertFalse( $results['auth-md'], 'A 200 HTML answer is not a file' );
 		$this->assertFalse( $results['sitemap-md'], 'A page behind a byte order mark is not a file' );
@@ -488,4 +498,79 @@ class DeclaredToAgentsTest extends WC_Unit_Test_Case {
 			$this->assertNull( $item['found'], $item['id'] );
 		}
 	}
+
+	/**
+	 * @testdox With WooCommerce's llms.txt fallback, its guidance is found when the served llms.txt holds it, from any provider; without the fallback the item isn't listed.
+	 */
+	public function test_llms_txt_guidance(): void {
+		$section = "## Agentic capabilities\n\n- [WooCommerce Store API](" . home_url( '/wp-json/wc/store/v1' ) . ')';
+		$sut     = new class() extends DeclaredToAgents {
+			/**
+			 * The status to report.
+			 *
+			 * @var array{status:string,section:string}|null
+			 */
+			public $status;
+
+			/**
+			 * The status set by the test.
+			 */
+			protected function llms_txt_status(): ?array {
+				return $this->status;
+			}
+		};
+		$found   = function ( array $responses ) use ( $sut ): array {
+			$this->results( $responses );
+			return array_column( $sut->all( wc_get_container()->get( StoreOutputChecks::class )->responses() ), 'found', 'id' );
+		};
+
+		$this->assertArrayNotHasKey( 'llms-txt-woocommerce-guidance', $found( array() ), 'Not listed without the fallback' );
+
+		$sut->status = array(
+			'status'  => 'unknown',
+			'section' => $section . "\n",
+		);
+		$this->assertTrue( $found( array( '/llms.txt' => array( 200, "# Shop\n\n" . $section . "\n" ) ) )['llms-txt-woocommerce-guidance'] );
+		$this->assertTrue(
+			$found(
+				array(
+					'/llms.txt' => array( 200, "# Shop\r\n\r\n" . str_replace( "\n", "\r\n", $section ) . "\r\n" ),
+				)
+			)['llms-txt-woocommerce-guidance'],
+			'CRLF line endings still match'
+		);
+		$this->assertFalse( $found( array( '/llms.txt' => array( 200, "# Shop\n\n- [About](" . home_url( '/about/' ) . ')' ) ) )['llms-txt-woocommerce-guidance'], 'Another provider\'s file without it' );
+		$this->assertFalse( $found( array() )['llms-txt-woocommerce-guidance'], 'No llms.txt' );
+		$this->assertNull( $found( array( '/llms.txt' => array( 503, '' ) ) )['llms-txt-woocommerce-guidance'], 'Couldn\'t check' );
+		$this->assertNull( $found( array( '/llms.txt' => array( 429, '' ) ) )['llms-txt-woocommerce-guidance'], 'Rate limited' );
+		$this->assertNull(
+			$found(
+				array(
+					'/llms.txt' => array( 200, "# Shop\n", array( 'content-length' => '999999' ) ),
+				)
+			)['llms-txt-woocommerce-guidance'],
+			'Truncated body with no match is couldn\'t check'
+		);
+		$this->assertNull(
+			$found(
+				array(
+					'/llms.txt' => array(
+						200,
+						"\n\n",
+						array(
+							'content-type'   => 'text/plain',
+							'content-length' => '999999',
+						),
+					),
+				)
+			)['llms-txt-woocommerce-guidance'],
+			'A body cut off in leading blank lines is couldn\'t check'
+		);
+
+		$sut->status = array(
+			'status'  => 'disabled',
+			'section' => '',
+		);
+		$this->assertArrayNotHasKey( 'llms-txt-woocommerce-guidance', $found( array() ), 'Not listed while WooCommerce adds no guidance' );
+	}
 }