Use WP Codebox v0.12.11 release (#132)

Author: chubes4

.github/workflows/README.md

@@ -12,7 +12,7 @@ The reusable workflow declares the expected typed review artifacts for Docs Agen
 
 The target repository grants `contents: write`, `pull-requests: write`, and `issues: write`. Docs Agent forwards the caller-scoped `${{ github.token }}` to WP Codebox for same-repository publication, so consumers do not configure `ACCESS_TOKEN`. `OPENAI_API_KEY` is an optional workflow secret and is required only for a live OpenAI run; skipped and dry-run calls do not require it. `EXTERNAL_PACKAGE_SOURCE_POLICY` remains a separate required v1 JSON secret. Migrate its value to the exact one-line JSON in the root README: it authorizes the selected Docs Agent package, the pinned Agents API component, the pinned PHP AI Client overlay, and the checksum-pinned OpenAI provider artifact. Both secrets are forwarded to WP Codebox without serialization into the task descriptor.
 
-Docs Agent consumes the released [WP Codebox v0.12.10](https://github.com/Automattic/wp-codebox/releases/tag/v0.12.10) workflow and passes the matching `wp_codebox_release_ref: v0.12.10` input. WP Codebox validates that the paired tags match, resolves the release tag, verifies its package version, materializes the declared native runtime closure, and transports the native task result through controlled `.codebox` result files before publishing the workflow result. Its published OpenAI/provider-model contract is validated against the declared provider metadata, and provider artifacts retain only canonical runtime-source provenance. Before persisting workflow results or artifact uploads, WP Codebox sanitizes private runtime paths from nested values, object keys, diagnostics, and command arguments. The native task request carries WP Codebox's versioned sandbox tool-policy snapshot, keeping runtime-visible tools explicit. See [WP Codebox #1767](https://github.com/Automattic/wp-codebox/issues/1767). Regression reference: [run `29305012941`](https://github.com/Automattic/wp-codebox/actions/runs/29305012941).
+Docs Agent consumes the released [WP Codebox v0.12.11](https://github.com/Automattic/wp-codebox/releases/tag/v0.12.11) workflow and passes the matching `wp_codebox_release_ref: v0.12.11` input. WP Codebox validates that the paired tags match, resolves the release tag, verifies its package version, materializes the declared native runtime closure, and transports the native task result through controlled `.codebox` result files before publishing the workflow result. Its published OpenAI/provider-model contract is validated against the declared provider metadata, and provider artifacts retain only canonical runtime-source provenance. Before persisting workflow results or artifact uploads, WP Codebox sanitizes private runtime paths from nested values, object keys, diagnostics, and command arguments. Uploads contain only allowlisted review artifacts plus the controlled workflow envelope, and lifecycle failures publish a normalized failed result even when artifact preparation cannot complete. The native task request carries WP Codebox's versioned sandbox tool-policy snapshot, keeping runtime-visible tools explicit. See [WP Codebox #1767](https://github.com/Automattic/wp-codebox/issues/1767) and [WP Codebox #1776](https://github.com/Automattic/wp-codebox/pull/1776). Regression reference: [run `29306539573`](https://github.com/Automattic/wp-codebox/actions/runs/29306539573).
 
 ## Docs Agent Runner Recipe
 

.github/workflows/maintain-docs.yml

@@ -238,9 +238,9 @@ jobs:
       contents: write
       pull-requests: write
       issues: write
-    uses: Automattic/wp-codebox/.github/workflows/run-agent-task.yml@v0.12.10
+    uses: Automattic/wp-codebox/.github/workflows/run-agent-task.yml@v0.12.11
     with:
-      wp_codebox_release_ref: v0.12.10
+      wp_codebox_release_ref: v0.12.11
       external_package_source: ${{ needs.prepare.outputs.external_package_source }}
       runtime_sources: ${{ needs.prepare.outputs.runtime_sources }}
       workload_id: docs-agent-${{ inputs.audience }}-${{ inputs.run_kind }}

.github/workflows/validate.yml

@@ -17,7 +17,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           repository: Automattic/wp-codebox
-          ref: v0.12.10
+          ref: v0.12.11
           path: .wp-codebox
       - name: Validate Docs Agent
         env:

tests/validate-docs-agent-bundle.php

@@ -196,11 +196,11 @@
 
 $transitional_homeboy_extensions_workflow = 'uses: Extra-Chill/homeboy-extensions/.github/workflows/runtime-agent-full-run.yml@main';
 $forbidden_docs_agent_codebox_workflow = 'uses: Automattic/wp-codebox/.github/workflows/docs-agent-runner.yml@main';
-$generic_codebox_agent_task_workflow = 'uses: Automattic/wp-codebox/.github/workflows/run-agent-task.yml@v0.12.10';
+$generic_codebox_agent_task_workflow = 'uses: Automattic/wp-codebox/.github/workflows/run-agent-task.yml@v0.12.11';
 $assert( ! str_contains( $maintain_docs_workflow, $transitional_homeboy_extensions_workflow ), 'maintain-docs.yml must not call Homeboy Extensions directly.' );
 $assert( ! str_contains( $maintain_docs_workflow, $forbidden_docs_agent_codebox_workflow ), 'maintain-docs.yml must not call a Codebox-owned Docs Agent wrapper.' );
 $assert( str_contains( $maintain_docs_workflow, $generic_codebox_agent_task_workflow ), 'maintain-docs.yml must call the generic Codebox agent-task workflow.' );
-$assert( str_contains( $maintain_docs_workflow, 'wp_codebox_release_ref: v0.12.10' ), 'maintain-docs.yml must pass the matching WP Codebox release tag.' );
+$assert( str_contains( $maintain_docs_workflow, 'wp_codebox_release_ref: v0.12.11' ), 'maintain-docs.yml must pass the matching WP Codebox release tag.' );
 
 $workflow_blocked_runtime_fragments = array_values( array_diff( $blocked_runtime_fragments, array( 'wp-codebox', 'Automattic/wp-codebox', 'OPENAI_API_KEY' ) ) );
 $workflow_internal_fragments = array_merge( $workflow_blocked_runtime_fragments, array( 'homeboy_extensions_ref:', 'runtime_ref:', 'runtime_ref }}', 'runtime_provider:', 'runtime_provider }}', 'runtime_profile:', 'runtime_profile }}', 'runtime_profiles:', 'runtime_profiles }}', 'runtime_execution:', 'runtime_execution }}', 'runtime_config:', 'runtime_config }}', 'component_contracts:', 'component_contracts }}', 'ability_requirements:', 'ability_requirements }}', 'runtime_components:', 'runtime_components }}', 'runtime_mounts:', 'runtime_mounts }}', 'required_abilities:', 'required_abilities }}', 'extra_wp_config_defines:' ) );
@@ -237,7 +237,9 @@
 foreach ( array( 'Docs Agent Runner Recipe', 'portable recipe', 'Docs Agent owns the native package' ) as $migration_note_text ) {
 	$assert( str_contains( $workflow_readme, $migration_note_text ), "Workflow README missing agent runtime note: {$migration_note_text}" );
 }
-$assert( str_contains( $workflow_readme, 'v0.12.10' ), 'Workflow README must record the WP Codebox release tag.' );
+$assert( str_contains( $workflow_readme, 'v0.12.11' ), 'Workflow README must record the WP Codebox release tag.' );
+$assert( str_contains( $workflow_readme, 'allowlisted review artifacts' ), 'Workflow README must document the WP Codebox upload allowlist.' );
+$assert( str_contains( $workflow_readme, 'normalized failed result' ), 'Workflow README must document normalized WP Codebox failures.' );
 $assert( str_contains( $workflow_readme, 'sanitizes private runtime paths' ), 'Workflow README must document private runtime-path sanitization.' );
 $assert( str_contains( $workflow_readme, 'https://github.com/Automattic/wp-codebox/issues/1767' ), 'Workflow README must link the WP Codebox runtime closure issue.' );
 $assert( str_contains( $workflow_readme, 'Docs Agent declares the runtime sources' ), 'Workflow README must document Docs Agent ownership of the runtime closure.' );

tests/validate-wp-codebox-run-agent-task-contract.php

@@ -54,6 +54,8 @@
 $run = $release['run'] ?? null;
 $assert( is_string( $run ) && preg_match( '/^\d+$/', $run ) === 1, 'WP Codebox release fixture must retain the regression run reference.' );
 $assert( true === ( $release['private_runtime_path_sanitization'] ?? null ), 'WP Codebox release fixture must require private runtime-path sanitization.' );
+$assert( true === ( $release['allowlisted_uploads'] ?? null ), 'WP Codebox release fixture must require allowlisted uploads.' );
+$assert( true === ( $release['normalized_failures'] ?? null ), 'WP Codebox release fixture must require normalized failures.' );
 $native_result_path = $release['native_result_path'] ?? null;
 $workflow_result_path = $release['workflow_result_path'] ?? null;
 $assert( '.codebox/native-agent-task-result.json' === $native_result_path, 'WP Codebox release fixture must declare the controlled native result path.' );
@@ -74,11 +76,17 @@
 $producer_upload = (string) file_get_contents( rtrim( $wp_codebox_dir, '/' ) . '/.github/scripts/run-agent-task/prepare-agent-task-upload.mjs' );
 $producer_sanitizer = (string) file_get_contents( rtrim( $wp_codebox_dir, '/' ) . '/.github/scripts/run-agent-task/runtime-source-sanitizer.mjs' );
 $producer_result = $read_json( rtrim( $wp_codebox_dir, '/' ) . '/contracts/agent-task-workflow-result.fixture.json' );
-$producer_path_regression = $read_json( rtrim( $wp_codebox_dir, '/' ) . '/fixtures/agent-task-runtime-paths-run-' . $run . '.json' );
-$assert( str_contains( $producer_workflow, $workflow_result_path ), 'WP Codebox producer workflow must upload the workflow result file.' );
+$producer_upload_regression = $read_json( rtrim( $wp_codebox_dir, '/' ) . '/fixtures/agent-task-upload-run-' . $run . '.json' );
+$assert( str_contains( $producer_workflow, 'workspace/.codebox/agent-task-upload' ), 'WP Codebox producer workflow must upload the controlled task bundle.' );
 $assert( str_contains( $producer_execute, '"--result-file", nativeResultPath' ), 'WP Codebox producer must pass the native result-file argument.' );
 $assert( str_contains( $producer_execute, 'const nativeResultPath = join(controlledCodeboxPath, "native-agent-task-result.json")' ), 'WP Codebox producer must constrain the native result path to .codebox.' );
 $assert( str_contains( $producer_execute, 'const resultPath = join(workspace, ".codebox", "agent-task-workflow-result.json")' ), 'WP Codebox producer must write the workflow result at the declared path.' );
+$assert( str_contains( $producer_execute, 'async function writeNormalizedFailure(error, request = {})' ), 'WP Codebox producer must normalize lifecycle failures into workflow results.' );
+$assert( str_contains( $producer_execute, 'status: "failed"' ) && str_contains( $producer_execute, 'success: false' ), 'WP Codebox normalized failures must report failed status.' );
+$assert( str_contains( $producer_upload, 'const declaredPaths = new Set(declaredArtifactPaths(result, declarations(request)))' ), 'WP Codebox uploads must derive artifacts from the declared allowlist.' );
+$assert( str_contains( $producer_upload, 'for (const path of declaredPaths)' ), 'WP Codebox uploads must stage only declared reviewer artifacts.' );
+$assert( str_contains( $producer_upload, 'agent-task-artifacts", "exclusions.json' ), 'WP Codebox uploads must report excluded source and undeclared artifacts.' );
+$assert( str_contains( $producer_workflow, 'workspace/.codebox/agent-task-upload' ) && str_contains( $producer_workflow, 'include-hidden-files: true' ), 'WP Codebox must upload the complete controlled hidden-file bundle.' );
 $assert( str_contains( $producer_execute, 'sandbox_tool_policy: {' ), 'WP Codebox producer must include an explicit sandbox tool-policy in the native task request.' );
 $assert( str_contains( $producer_execute, 'schema: "wp-codebox/sandbox-tool-policy/v1"' ), 'WP Codebox producer sandbox tool-policy must use the published schema.' );
 $assert( str_contains( $producer_execute, 'version: 1' ), 'WP Codebox producer sandbox tool-policy must declare its contract version.' );
@@ -212,10 +220,9 @@
 $assert( str_contains( $producer_upload, 'sanitizeRuntimeSourceJson(text, runtimeSourceRoots)' ), 'WP Codebox must sanitize private runtime paths from artifact uploads.' );
 $assert( str_contains( $producer_sanitizer, 'RUNTIME_SOURCE_PLACEHOLDER = "[runtime-source]"' ), 'WP Codebox must replace private runtime paths with the published placeholder.' );
 $assert( str_contains( $producer_sanitizer, 'PRIVATE_RUNTIME_SOURCE_FIELDS = new Set(["source_package_root"])' ), 'WP Codebox must remove private runtime source-root fields.' );
-$private_runtime_root = $producer_path_regression['runtime_root'] ?? null;
-$assert( is_string( $private_runtime_root ) && '' !== $private_runtime_root, 'WP Codebox private-path regression fixture must declare the private runtime root.' );
-$assert( str_contains( (string) ( $producer_path_regression['failure']['stack'] ?? '' ), $private_runtime_root ), 'WP Codebox private-path regression fixture must cover stack traces.' );
-$assert( array_key_exists( $private_runtime_root . '/key', $producer_path_regression['success']['outputs']['metadata']['nested'] ?? array() ), 'WP Codebox private-path regression fixture must cover object keys.' );
+$assert( (string) $run === ( $producer_upload_regression['run_id'] ?? null ), 'WP Codebox upload regression fixture must match the recorded run.' );
+$assert( 'failed-on-runtime-source' === ( $producer_upload_regression['observed']['upload_preparation'] ?? null ), 'WP Codebox upload regression fixture must retain the runtime-source failure.' );
+$assert( in_array( '.codebox/agent-task-request.json', $producer_upload_regression['observed']['uploaded'] ?? array(), true ), 'WP Codebox upload regression fixture must retain the controlled request upload.' );
 $assert( ! array_intersect( array( 'MODEL_PROVIDER_SECRET_1', 'MODEL_PROVIDER_SECRET_2', 'MODEL_PROVIDER_SECRET_3', 'MODEL_PROVIDER_SECRET_4', 'MODEL_PROVIDER_SECRET_5' ), array_keys( $caller_secrets ) ), 'Docs Agent must forward only the OPENAI_API_KEY provider secret name.' );
 
 preg_match( "/output_projections='(?<json>[^']+)'/", $workflow, $projection_match );

tests/wp-codebox-release.fixture.json

@@ -1,8 +1,10 @@
 {
-  "tag": "v0.12.10",
-  "package_version": "0.12.10",
-  "run": "29305012941",
+  "tag": "v0.12.11",
+  "package_version": "0.12.11",
+  "run": "29306539573",
   "private_runtime_path_sanitization": true,
+  "allowlisted_uploads": true,
+  "normalized_failures": true,
   "native_result_path": ".codebox/native-agent-task-result.json",
   "workflow_result_path": ".codebox/agent-task-workflow-result.json"
 }