From 74100eb1bfc764c0a2aa69e16385af7e47fec3c4 Mon Sep 17 00:00:00 2001 From: Chris Huber Date: Sun, 19 Jul 2026 09:05:09 -0400 Subject: [PATCH] Advance Docs Agent producer chain --- .github/workflows/ci.yml | 4 ++-- .github/workflows/docs-agent.yml | 2 +- docs/docs-agent-workflow.md | 12 ++++++------ tests/docs-agent-native-workflow-contract.php | 16 ++++++++-------- 4 files changed, 17 insertions(+), 17 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index eb981df..b1cca01 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -53,14 +53,14 @@ jobs: uses: actions/checkout@v6.0.3 with: repository: Automattic/docs-agent - ref: 37d2c49251bc402852d301d9d5b42a105413f13e + ref: 06a7e92e0f4d265d09bbdb6dae1ec78fd8e7c825 path: .docs-agent-producer - name: Checkout WP Codebox producer schema uses: actions/checkout@v6.0.3 with: repository: Automattic/wp-codebox - ref: v0.12.23 + ref: v0.12.29 path: .wp-codebox-producer - name: Set up PHP diff --git a/.github/workflows/docs-agent.yml b/.github/workflows/docs-agent.yml index 797861c..69e78bd 100644 --- a/.github/workflows/docs-agent.yml +++ b/.github/workflows/docs-agent.yml @@ -20,7 +20,7 @@ concurrency: jobs: docs-agent: name: Maintain Technical Documentation - uses: Automattic/docs-agent/.github/workflows/maintain-docs.yml@37d2c49251bc402852d301d9d5b42a105413f13e + uses: Automattic/docs-agent/.github/workflows/maintain-docs.yml@06a7e92e0f4d265d09bbdb6dae1ec78fd8e7c825 with: audience: technical run_kind: maintenance diff --git a/docs/docs-agent-workflow.md b/docs/docs-agent-workflow.md index 71a35da..b611773 100644 --- a/docs/docs-agent-workflow.md +++ b/docs/docs-agent-workflow.md @@ -7,7 +7,7 @@ Agents API publishes its canonical documentation updates through the repository- The consumer workflow is named **Docs Agent** and dispatches the reusable Docs Agent workflow from Automattic/docs-agent at the exact pinned revision: ```text -Automattic/docs-agent/.github/workflows/maintain-docs.yml@4c1043510ae71be4750cfde69777efc95ae0001e +Automattic/docs-agent/.github/workflows/maintain-docs.yml@06a7e92e0f4d265d09bbdb6dae1ec78fd8e7c825 ``` The workflow contract is intentionally narrow: @@ -32,8 +32,8 @@ DOCS_AGENT_DIR=/path/to/docs-agent WP_CODEBOX_DIR=/path/to/wp-codebox php tests/ The required producer checkouts are: -- Docs Agent revision `4c1043510ae71be4750cfde69777efc95ae0001e`. -- WP Codebox ref `v0.12.21`, revision `b5b1fc7eef4367d5e403de3e373df91d3722965b`. +- Docs Agent revision `06a7e92e0f4d265d09bbdb6dae1ec78fd8e7c825`. +- WP Codebox ref `v0.12.29`, revision `bc982947ec33c78160125026e16d357b7ece3ea1`. At that Docs Agent revision, the `technical:maintenance` lane maps to the native package: @@ -41,15 +41,15 @@ At that Docs Agent revision, the `technical:maintenance` lane maps to the native bundles/technical-docs-agent/native/technical-docs-maintenance-agent.agent.json ``` -with agent slug `technical-docs-maintenance-agent`, package digest `sha256-bytes-v1:6057aad4eb7c5f0320ccfbce9da93a5fa1d3fc521478b5571ed81c28129325aa`, and `success_requires_pr=false`. +with agent slug `technical-docs-maintenance-agent`, package-source revision `85443eb91c12b2759d8e207f1ae4421407b4cc5e`, package digest `sha256-bytes-v1:78fef9f8d787866c7b48b8f044769d38c0528778c8e2a82af816f9f8ea65014f`, and `lane_requires_pr=false`. Docs Agent then calls WP Codebox's reusable workflow: ```text -Automattic/wp-codebox/.github/workflows/run-agent-task.yml@v0.12.21 +Automattic/wp-codebox/.github/workflows/run-agent-task.yml@v0.12.29 ``` -The contract test verifies that this WP Codebox producer exposes the `wp-codebox/reusable-workflow-interface/v1` schema and preserves the release, external-package, runtime-source, target repository, writable path, verification, drift-check, publication, access-repository, and allowed-repository chain. In that producer path, WP Codebox v0.12.21 is the component that runs the agent task and returns the reviewer-safe result projection used by the reusable workflow publication path. +The contract test verifies that this WP Codebox producer exposes the `wp-codebox/reusable-workflow-interface/v1` schema and preserves the release, external-package, runtime-source, target repository, writable path, verification, drift-check, publication, access-repository, and allowed-repository chain. In that producer path, WP Codebox v0.12.29 runs the agent task and returns the reviewer-safe result projection used by the reusable workflow publication path. Successful publication verification returns `{ valid: true }` without a failure-only `error`; repository mismatches retain their exact diagnostic. ## Secrets And Publication Credentials diff --git a/tests/docs-agent-native-workflow-contract.php b/tests/docs-agent-native-workflow-contract.php index ae71111..77424bf 100644 --- a/tests/docs-agent-native-workflow-contract.php +++ b/tests/docs-agent-native-workflow-contract.php @@ -2,8 +2,8 @@ /** * Validate the Docs Agent consumer against its pinned native producer chain. * - * Run with DOCS_AGENT_DIR at Docs Agent #148's merge commit and WP_CODEBOX_DIR - * at WP Codebox v0.12.23. This test intentionally fails without + * Run with DOCS_AGENT_DIR at Docs Agent #165's merge commit and WP_CODEBOX_DIR + * at WP Codebox v0.12.29. This test intentionally fails without * both checkouts because it verifies the producer interfaces, not just copies * of their expected values in this repository. * @@ -12,9 +12,9 @@ declare( strict_types=1 ); -const AGENTS_API_DOCS_AGENT_REVISION = '37d2c49251bc402852d301d9d5b42a105413f13e'; -const AGENTS_API_WP_CODEBOX_REF = 'v0.12.23'; -const AGENTS_API_WP_CODEBOX_REVISION = 'a2b02cd99ba645ba2250bf58c943bdd1eb13e690'; +const AGENTS_API_DOCS_AGENT_REVISION = '06a7e92e0f4d265d09bbdb6dae1ec78fd8e7c825'; +const AGENTS_API_WP_CODEBOX_REF = 'v0.12.29'; +const AGENTS_API_WP_CODEBOX_REVISION = 'bc982947ec33c78160125026e16d357b7ece3ea1'; $root = dirname( __DIR__ ); $failures = array(); @@ -103,7 +103,7 @@ function agents_api_docs_agent_contract_match( string $content, string $pattern, } } -agents_api_docs_agent_contract_match( $consumer_workflow, '~^\s*uses:\s*Automattic/docs-agent/\.github/workflows/maintain-docs\.yml@' . AGENTS_API_DOCS_AGENT_REVISION . '\s*$~m', 'Consumer must pin Docs Agent #148.', $failures ); +agents_api_docs_agent_contract_match( $consumer_workflow, '~^\s*uses:\s*Automattic/docs-agent/\.github/workflows/maintain-docs\.yml@' . AGENTS_API_DOCS_AGENT_REVISION . '\s*$~m', 'Consumer must pin Docs Agent #165.', $failures ); agents_api_docs_agent_contract_match( $consumer_workflow, '~^\s*audience:\s*technical\s*$~m', 'Consumer audience must be technical.', $failures ); agents_api_docs_agent_contract_match( $consumer_workflow, '~^\s*run_kind:\s*maintenance\s*$~m', 'Consumer run kind must be maintenance.', $failures ); agents_api_docs_agent_contract_match( $consumer_workflow, '~^\s*base_ref:\s*main\s*$~m', 'Consumer target base must be main.', $failures ); @@ -119,8 +119,8 @@ function agents_api_docs_agent_contract_match( string $content, string $pattern, agents_api_docs_agent_contract_match( $consumer_workflow, '~^\s*' . preg_quote( $permission, '~' ) . '\s*$~m', "Consumer must grant {$permission} for built-in-token publication.", $failures ); } -agents_api_docs_agent_contract_match( $docs_workflow, '~technical:maintenance\)\s+package_path="bundles/technical-docs-agent/native/technical-docs-maintenance-agent\.agent\.json"\s+agent_slug="technical-docs-maintenance-agent"\s+package_digest="sha256-bytes-v1:6057aad4eb7c5f0320ccfbce9da93a5fa1d3fc521478b5571ed81c28129325aa"\s+success_requires_pr=false~s', 'Docs Agent #148 technical maintenance lane must map to its exact native package.', $failures ); -agents_api_docs_agent_contract_match( $docs_workflow, '~uses:\s*Automattic/wp-codebox/\.github/workflows/run-agent-task\.yml@' . preg_quote( AGENTS_API_WP_CODEBOX_REF, '~' ) . '~', 'Docs Agent must pin WP Codebox v0.12.23.', $failures ); +agents_api_docs_agent_contract_match( $docs_workflow, '~technical:maintenance\)\s+package_path="bundles/technical-docs-agent/native/technical-docs-maintenance-agent\.agent\.json"\s+agent_slug="technical-docs-maintenance-agent"\s+package_digest="sha256-bytes-v1:78fef9f8d787866c7b48b8f044769d38c0528778c8e2a82af816f9f8ea65014f"\s+lane_requires_pr=false~s', 'Docs Agent #165 technical maintenance lane must map to its exact native package.', $failures ); +agents_api_docs_agent_contract_match( $docs_workflow, '~uses:\s*Automattic/wp-codebox/\.github/workflows/run-agent-task\.yml@' . preg_quote( AGENTS_API_WP_CODEBOX_REF, '~' ) . '~', 'Docs Agent must pin WP Codebox v0.12.29.', $failures ); agents_api_docs_agent_contract_match( $docs_workflow, '~wp_codebox_release_ref:\s*' . preg_quote( AGENTS_API_WP_CODEBOX_REF, '~' ) . '.*?external_package_source:\s*\$\{\{ needs\.prepare\.outputs\.external_package_source \}\}.*?runtime_sources:\s*\$\{\{ needs\.prepare\.outputs\.runtime_sources \}\}.*?target_repo:\s*\$\{\{ github\.repository \}\}.*?writable_paths:\s*\$\{\{ inputs\.writable_paths \}\}.*?verification_commands:\s*\$\{\{ needs\.prepare\.outputs\.verification_commands \}\}.*?drift_checks:\s*\$\{\{ needs\.prepare\.outputs\.drift_checks \}\}.*?success_requires_pr:\s*\$\{\{ needs\.prepare\.outputs\.success_requires_pr == \'true\' \}\}.*?access_token_repos:\s*\$\{\{ github\.repository \}\}.*?allowed_repos:\s*\'\["\$\{\{ github\.repository \}\}"\]\'~s', 'Docs Agent must preserve the WP Codebox release, external-package, runtime-source, target, writable, verification, publication, and access chain.', $failures ); agents_api_docs_agent_contract_match( $docs_workflow, '~OPENAI_API_KEY:\s*\$\{\{ secrets\.OPENAI_API_KEY \}\}\s+ACCESS_TOKEN:\s*\$\{\{ github\.token \}\}\s+EXTERNAL_PACKAGE_SOURCE_POLICY:\s*\$\{\{ secrets\.EXTERNAL_PACKAGE_SOURCE_POLICY \}\}~s', 'Docs Agent must forward caller credentials and its built-in publication token.', $failures );