Use WP Codebox v0.12.13 release (#134)

Author: chubes4

.github/workflows/README.md

@@ -1,18 +1,18 @@
 # Docs Agent Workflows
 
-`maintain-docs.yml` is the consumer-facing reusable workflow for scheduled upkeep. Consumer repositories pass product-level inputs such as `audience`, `base_ref`, `docs_branch`, `writable_paths`, `verification_commands`, `drift_checks`, `prompt`, `run_agent`, and `dry_run`.
+`maintain-docs.yml` is the consumer-facing reusable workflow for scheduled upkeep. Consumer repositories pass product-level inputs such as `audience`, `base_ref`, `docs_branch`, `writable_paths`, `validation_dependencies`, `verification_commands`, `drift_checks`, `prompt`, `run_agent`, and `dry_run`.
 
 The consumer workflow supports separate lanes for technical docs, user docs, and live skills maintenance. Use `audience: skills` with skills/package writable paths instead of broad docs paths.
 
 Schedule skills upkeep separately from docs upkeep. The skills lane should use a dedicated branch such as `docs-agent/skills-upkeep`, skill/package writable paths, verification commands, and drift checks through the portable recipe.
 
-When verification commands or drift checks are needed, pass them through the reusable workflow inputs above. The reusable workflow includes those executable inputs in the portable recipe and keeps the target repository as the writable Docs Agent workspace.
+When validation setup, verification commands, or drift checks are needed, pass them through the reusable workflow inputs above. `validation_dependencies` is an optional caller-owned command that runs before verification during a live execution. The reusable workflow includes those executable inputs in the portable recipe and keeps the target repository as the writable Docs Agent workspace.
 
 The reusable workflow declares the expected typed review artifacts for Docs Agent runs: transcript, change summary, verification report, drift report, and workspace publication links. `maintain-docs.yml` writes those declarations into the portable recipe and exposes the declaration objects through `declared_artifacts_json`.
 
 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.12](https://github.com/Automattic/wp-codebox/releases/tag/v0.12.12) workflow and passes the matching `wp_codebox_release_ref: v0.12.12` 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. Diagnostic messages that name runtime classes remain reviewable; PHP-shaped runtime source remains blocked even under a reviewer-safe extension. 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 #1778](https://github.com/Automattic/wp-codebox/pull/1778). Regression reference: [run `29307978522`](https://github.com/Automattic/wp-codebox/actions/runs/29307978522).
+Docs Agent consumes the released [WP Codebox v0.12.13](https://github.com/Automattic/wp-codebox/releases/tag/v0.12.13) workflow and passes the matching `wp_codebox_release_ref: v0.12.13` 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. Diagnostic messages that name runtime classes remain reviewable; PHP-shaped runtime source remains blocked even under a reviewer-safe extension. The native task request carries WP Codebox's versioned sandbox tool-policy snapshot, keeping runtime-visible tools explicit. v0.12.13 supports optional output projection descriptors and derives required artifacts from typed declarations, so a successful maintenance no-op has no required artifacts or publication output. See [WP Codebox #1767](https://github.com/Automattic/wp-codebox/issues/1767), [WP Codebox #1778](https://github.com/Automattic/wp-codebox/pull/1778), and [WP Codebox #1780](https://github.com/Automattic/wp-codebox/pull/1780). Regression reference: [run `29309360438`](https://github.com/Automattic/build-with-wordpress/actions/runs/29309360438).
 
 ## Docs Agent Runner Recipe
 

.github/workflows/maintain-docs.yml

@@ -27,6 +27,10 @@ env:
         description: Comma-separated paths Docs Agent may edit.
         type: string
         default: README.md,docs/**
+      validation_dependencies:
+        description: Optional caller-owned command that installs dependencies needed before validation.
+        type: string
+        default: ""
       verification_commands:
         description: JSON array of canonical runner verification commands executed in the target workspace.
         type: string
@@ -76,6 +80,9 @@ env:
       success_requires_pr:
         description: Whether the selected lane requires a published pull request for success.
         value: ${{ jobs.prepare.outputs.success_requires_pr }}
+      validation_dependencies:
+        description: Caller-owned validation dependency command included in the runner recipe.
+        value: ${{ jobs.prepare.outputs.validation_dependencies }}
 
 jobs:
   prepare:
@@ -88,6 +95,7 @@ jobs:
       external_package_source: ${{ steps.config.outputs.external_package_source }}
       runtime_sources: ${{ steps.config.outputs.runtime_sources }}
       prompt: ${{ steps.config.outputs.prompt }}
+      validation_dependencies: ${{ steps.config.outputs.validation_dependencies }}
       verification_commands: ${{ steps.config.outputs.verification_commands }}
       drift_checks: ${{ steps.config.outputs.drift_checks }}
       runner_workspace: ${{ steps.config.outputs.runner_workspace }}
@@ -102,6 +110,7 @@ jobs:
           RUN_KIND: ${{ inputs.run_kind }}
           INPUT_VERIFICATION_COMMANDS: ${{ inputs.verification_commands }}
           INPUT_DRIFT_CHECKS: ${{ inputs.drift_checks }}
+          INPUT_VALIDATION_DEPENDENCIES: ${{ inputs.validation_dependencies }}
           INPUT_PROMPT: ${{ inputs.prompt }}
           INPUT_WRITABLE_PATHS: ${{ inputs.writable_paths }}
           RUN_AGENT: ${{ inputs.run_agent }}
@@ -201,11 +210,12 @@ jobs:
             --arg writablePaths "$INPUT_WRITABLE_PATHS" \
             --arg baseRef "$INPUT_BASE_REF" \
             --arg docsBranch "$INPUT_DOCS_BRANCH" \
+            --arg validationDependencies "$INPUT_VALIDATION_DEPENDENCIES" \
             --argjson successRequiresPr "$success_requires_pr" \
             --argjson verificationCommands "$verification_commands" \
             --argjson driftChecks "$drift_checks" \
             --argjson artifactDeclarations "$artifact_declarations" \
-            '{schema:"docs-agent/runner-recipe/v1",targetRepository:$targetRepository,prompt:$prompt,docsAgent:{externalPackageSource:{repository:$repository,revision:$revision,path:$packagePath,digest:$packageDigest},agentSlug:$agentSlug},runner:{verificationCommands:$verificationCommands,driftChecks:$driftChecks,writablePaths:$writablePaths,baseRef:$baseRef,docsBranch:$docsBranch,successRequiresPr:$successRequiresPr},artifacts:{expected:($artifactDeclarations|map(.name)),declarations:$artifactDeclarations}}')"
+            '{schema:"docs-agent/runner-recipe/v1",targetRepository:$targetRepository,prompt:$prompt,docsAgent:{externalPackageSource:{repository:$repository,revision:$revision,path:$packagePath,digest:$packageDigest},agentSlug:$agentSlug},runner:{validationDependencies:$validationDependencies,verificationCommands:$verificationCommands,driftChecks:$driftChecks,writablePaths:$writablePaths,baseRef:$baseRef,docsBranch:$docsBranch,successRequiresPr:$successRequiresPr},artifacts:{expected:($artifactDeclarations|map(.name)),declarations:$artifactDeclarations}}')"
           external_package_source="$(jq -cn --arg repository "Automattic/docs-agent" --arg revision "$DOCS_AGENT_PACKAGE_REVISION" --arg path "$package_path" --arg digest "$package_digest" '{repository:$repository,revision:$revision,path:$path,digest:$digest}')"
           runtime_sources='[{"version":1,"role":"component","repository":"Automattic/agents-api","revision":"59d1e6b473f22498e40e279130bbb4f9bcde3b73","path":".","metadata":{"slug":"agents-api","loadAs":"mu-plugin","pluginFile":"agents-api.php"}},{"version":1,"role":"provider_plugin","source":{"type":"https_zip","url":"https://downloads.wordpress.org/plugin/ai-provider-for-openai.1.0.3.zip","sha256":"48f3c0c714b3164cda79d320829830d5a0ea1116e0b19653da8af898a22d3bb6","archive_root":"ai-provider-for-openai"},"metadata":{"slug":"ai-provider-for-openai","pluginFile":"plugin.php","activate":true,"providers":["openai"]}},{"version":1,"role":"bundled_library","repository":"WordPress/php-ai-client","revision":"631704201d15ffeff7091ad3bc7156db74054956","path":".","metadata":{"library":"php-ai-client","strategy":"wordpress-scoped-bundle"}}]'
 
@@ -215,14 +225,15 @@ jobs:
             --arg baseRef "$INPUT_BASE_REF" \
             '{enabled:true,repo:$repo,clone_url:("https://github.com/" + $repo + ".git"),branch:$branch,branch_prefix:$branch,from:("origin/" + $baseRef)}')"
           expected_artifacts="$(printf '%s' "$artifact_declarations" | jq -c 'map(.name)')"
-          output_projections='{"docs_agent_publication":"metadata.runner_workspace_publication.url"}'
+          output_projections="$(jq -cn --arg path 'metadata.runner_workspace_publication.url' --argjson required "$success_requires_pr" '{docs_agent_publication:{path:$path,required:$required}}')"
 
           {
             printf 'recipe_json<<EOF\n%s\nEOF\n' "$recipe_json"
             printf 'artifact_declarations<<EOF\n%s\nEOF\n' "$artifact_declarations"
             printf 'external_package_source=%s\n' "$external_package_source"
             printf 'runtime_sources<<EOF\n%s\nEOF\n' "$runtime_sources"
             printf 'prompt<<EOF\n%s\nEOF\n' "$prompt"
+            printf 'validation_dependencies<<EOF\n%s\nEOF\n' "$INPUT_VALIDATION_DEPENDENCIES"
             printf 'verification_commands<<EOF\n%s\nEOF\n' "$verification_commands"
             printf 'drift_checks<<EOF\n%s\nEOF\n' "$drift_checks"
             printf 'runner_workspace<<EOF\n%s\nEOF\n' "$runner_workspace"
@@ -238,9 +249,9 @@ jobs:
       contents: write
       pull-requests: write
       issues: write
-    uses: Automattic/wp-codebox/.github/workflows/run-agent-task.yml@v0.12.12
+    uses: Automattic/wp-codebox/.github/workflows/run-agent-task.yml@v0.12.13
     with:
-      wp_codebox_release_ref: v0.12.12
+      wp_codebox_release_ref: v0.12.13
       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 }}
@@ -250,6 +261,7 @@ jobs:
       prompt: ${{ needs.prepare.outputs.prompt }}
       writable_paths: ${{ inputs.writable_paths }}
       runner_workspace: ${{ needs.prepare.outputs.runner_workspace }}
+      validation_dependencies: ${{ needs.prepare.outputs.validation_dependencies }}
       verification_commands: ${{ needs.prepare.outputs.verification_commands }}
       drift_checks: ${{ needs.prepare.outputs.drift_checks }}
       success_requires_pr: ${{ needs.prepare.outputs.success_requires_pr == 'true' }}

.github/workflows/validate.yml

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

README.md

@@ -113,7 +113,7 @@ Docs Agent declares the review artifacts it expects the runner to materialize as
 
 Docs Agent owns native package selection, lane, artifact, prompt, and workspace mapping. Execution, credentials, AI provider selection, sandboxing, and publication are runner-owned concerns outside this repository.
 
-Portable recipe fields include `docsAgent`, `runner.writablePaths`, artifacts, verification commands, drift checks, and review output mapping suggestions.
+Portable recipe fields include `docsAgent`, `runner.writablePaths`, caller-owned `runner.validationDependencies`, artifacts, verification commands, drift checks, and review output mapping suggestions.
 
 ## Pull Request Behavior
 
@@ -122,7 +122,8 @@ Docs Agent opens or updates one canonical PR for the configured branch.
 - If the selected surface is current, the run succeeds with no changes.
 - If maintenance is needed, changes are written only under `writable_paths`.
 - If the canonical PR is already open, later runs reuse the same `docs_branch` and PR instead of creating duplicates.
-- `job_status`, `transcript_summary`, `credential_mode`, `success_requires_pr`, and bounded `projected_outputs_json` are exposed as reusable workflow outputs. A `run_agent: false` call returns `job_status: skipped`; a `dry_run: true` call validates without starting a model run. `OPENAI_API_KEY` is only required for a live OpenAI run and is never included in recipes, workflow outputs, or artifacts. Bootstrap lanes require a published pull request for success and expose its URL through `projected_outputs_json`; maintenance lanes allow a no-change result. Typed artifact declarations are exposed as `declared_artifacts_json` for review/debugging. Raw engine data is retained in runner artifacts rather than exposed as a workflow output.
+- `validation_dependencies` is an optional caller-owned reusable-workflow input. It is passed through the portable recipe and runs before verification commands when a live runner execution needs setup.
+- `job_status`, `transcript_summary`, `credential_mode`, `success_requires_pr`, `validation_dependencies`, and bounded `projected_outputs_json` are exposed as reusable workflow outputs. A `run_agent: false` call returns `job_status: skipped`; a `dry_run: true` call validates without starting a model run. `OPENAI_API_KEY` is only required for a live OpenAI run and is never included in recipes, workflow outputs, or artifacts. Bootstrap lanes require a published pull request and its projected URL for success; maintenance lanes allow a no-change result with no publication projection. Typed artifact declarations remain optional and are exposed as `declared_artifacts_json` for review/debugging. Raw engine data is retained in runner artifacts rather than exposed as a workflow output.
 
 ## Quality Bar