Forward native runner credentials and publication policy (#121)

Author: chubes4

.github/workflows/README.md

@@ -1,6 +1,6 @@
 # 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`, and `run_agent`.
+`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`.
 
 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.
 
@@ -10,7 +10,7 @@ When verification commands or drift checks are needed, pass them through the reu
 
 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 must pass `ACCESS_TOKEN` and `EXTERNAL_PACKAGE_SOURCE_POLICY`. `ACCESS_TOKEN` authorizes target-repository publication. The policy is a separate v1 JSON secret that authorizes only the selected public standalone Docs Agent package; it is forwarded to WP Codebox as a secret and never serialized into the task descriptor. Same-organization callers can use `secrets: inherit` with both secrets; cross-organization callers map each secret explicitly.
+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 that authorizes only the selected public standalone Docs Agent package. Both secrets are forwarded to WP Codebox without serialization into the task descriptor.
 
 ## Docs Agent Runner Recipe
 

.github/workflows/maintain-docs.yml

@@ -39,10 +39,14 @@ name: Maintain Docs
         description: Run the prepared Docs Agent task through the generic Codebox agent-task workflow.
         type: boolean
         default: true
+      dry_run:
+        description: Validate the prepared Docs Agent task without starting a live agent run.
+        type: boolean
+        default: false
     secrets:
-      ACCESS_TOKEN:
-        description: GitHub token authorized to read, push, and open pull requests in the calling repository.
-        required: true
+      OPENAI_API_KEY:
+        description: Optional OpenAI credential used for live Docs Agent runs.
+        required: false
       EXTERNAL_PACKAGE_SOURCE_POLICY:
         description: Version 1 JSON policy authorizing Docs Agent standalone native packages.
         required: true
@@ -65,6 +69,9 @@ name: Maintain Docs
       credential_mode:
         description: Normalized native runner credential mode.
         value: ${{ jobs.run-agent.outputs.credential_mode }}
+      success_requires_pr:
+        description: Whether the selected lane requires a published pull request for success.
+        value: ${{ jobs.prepare.outputs.success_requires_pr }}
 
 jobs:
   prepare:
@@ -81,6 +88,7 @@ jobs:
       runner_workspace: ${{ steps.config.outputs.runner_workspace }}
       expected_artifacts: ${{ steps.config.outputs.expected_artifacts }}
       output_projections: ${{ steps.config.outputs.output_projections }}
+      success_requires_pr: ${{ steps.config.outputs.success_requires_pr }}
     steps:
       - name: Resolve Docs Agent settings
         id: config
@@ -91,6 +99,9 @@ jobs:
           INPUT_DRIFT_CHECKS: ${{ inputs.drift_checks }}
           INPUT_PROMPT: ${{ inputs.prompt }}
           INPUT_WRITABLE_PATHS: ${{ inputs.writable_paths }}
+          RUN_AGENT: ${{ inputs.run_agent }}
+          DRY_RUN: ${{ inputs.dry_run }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           DOCS_AGENT_REVISION: ${{ github.job_workflow_sha }}
           INPUT_DOCS_BRANCH: ${{ inputs.docs_branch }}
           INPUT_BASE_REF: ${{ inputs.base_ref }}
@@ -105,30 +116,35 @@ jobs:
               package_path="bundles/technical-docs-agent/native/technical-docs-bootstrap-agent.agent.json"
               agent_slug="technical-docs-bootstrap-agent"
               package_digest="sha256-bytes-v1:9050c9b4364a5a91b057fd51ff5f667efc320f9d6776160ab3e7cf4fd5e4f0e6"
+              success_requires_pr=true
               default_prompt="Bootstrap source-grounded developer documentation that helps developers understand, use, and extend the code in the repository."
               ;;
             technical:maintenance)
               package_path="bundles/technical-docs-agent/native/technical-docs-maintenance-agent.agent.json"
               agent_slug="technical-docs-maintenance-agent"
               package_digest="sha256-bytes-v1:6057aad4eb7c5f0320ccfbce9da93a5fa1d3fc521478b5571ed81c28129325aa"
+              success_requires_pr=false
               default_prompt="Maintain source-grounded developer documentation that helps developers understand, use, and extend the code in the repository."
               ;;
             user:bootstrap)
               package_path="bundles/user-docs-agent/native/user-docs-bootstrap-agent.agent.json"
               agent_slug="user-docs-bootstrap-agent"
               package_digest="sha256-bytes-v1:ee558a73f2a393c1912d62f7f40dbdd4bc31ac0168c3c248316b3430258c55cd"
+              success_requires_pr=true
               default_prompt="Bootstrap source-grounded product documentation for onboarding, setup, common tasks, expected outcomes, permissions, compatibility, troubleshooting, and FAQs."
               ;;
             user:maintenance)
               package_path="bundles/user-docs-agent/native/user-docs-maintenance-agent.agent.json"
               agent_slug="user-docs-maintenance-agent"
               package_digest="sha256-bytes-v1:e2248f014c1409a8d4c5cb303ea37c0b24ae05babd02d40c6032160daf60d4c4"
+              success_requires_pr=false
               default_prompt="Maintain source-grounded product documentation for onboarding, setup, common tasks, expected outcomes, permissions, compatibility, troubleshooting, and FAQs."
               ;;
             skills:maintenance)
               package_path="bundles/skills-agent/native/skills-maintenance-agent.agent.json"
               agent_slug="skills-maintenance-agent"
               package_digest="sha256-bytes-v1:c643f8bd31864cdd607f9025a000694a65a3fdf91532e4311fbac541e708a2b2"
+              success_requires_pr=false
               default_prompt="Maintain live agent skill instructions and generated packaged skill outputs."
               ;;
             *)
@@ -137,6 +153,11 @@ jobs:
               ;;
           esac
 
+          if [ "$RUN_AGENT" = true ] && [ "$DRY_RUN" != true ] && [ -z "$OPENAI_API_KEY" ]; then
+            printf 'OPENAI_API_KEY is required when run_agent=true for the openai provider. Set run_agent=false or dry_run=true for an explicit non-live path.\n' >&2
+            exit 1
+          fi
+
           verification_commands="$(printf '%s' "$INPUT_VERIFICATION_COMMANDS" | jq -c 'if type == "array" then . else error("verification_commands must be an array") end')"
           drift_checks="$(printf '%s' "$INPUT_DRIFT_CHECKS" | jq -c 'if type == "array" then . else error("drift_checks must be an array") end')"
           if ! printf '%s' "$DOCS_AGENT_REVISION" | grep -Eq '^[0-9a-fA-F]{40}$'; then
@@ -176,10 +197,11 @@ jobs:
             --arg writablePaths "$INPUT_WRITABLE_PATHS" \
             --arg baseRef "$INPUT_BASE_REF" \
             --arg docsBranch "$INPUT_DOCS_BRANCH" \
+            --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},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:{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_REVISION" --arg path "$package_path" --arg digest "$package_digest" '{repository:$repository,revision:$revision,path:$path,digest:$digest}')"
 
           runner_workspace="$(jq -cn \
@@ -200,11 +222,16 @@ jobs:
             printf 'runner_workspace<<EOF\n%s\nEOF\n' "$runner_workspace"
             printf 'expected_artifacts<<EOF\n%s\nEOF\n' "$expected_artifacts"
             printf 'output_projections<<EOF\n%s\nEOF\n' "$output_projections"
+            printf 'success_requires_pr=%s\n' "$success_requires_pr"
           } >> "$GITHUB_OUTPUT"
 
   run-agent:
     name: Run Docs Agent
     needs: prepare
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
     uses: Automattic/wp-codebox/.github/workflows/run-agent-task.yml@54c2f9a7bc3cd1fe20055d496c83efcfb99afb41
     with:
       external_package_source: ${{ needs.prepare.outputs.external_package_source }}
@@ -217,7 +244,7 @@ jobs:
       runner_workspace: ${{ needs.prepare.outputs.runner_workspace }}
       verification_commands: ${{ needs.prepare.outputs.verification_commands }}
       drift_checks: ${{ needs.prepare.outputs.drift_checks }}
-      success_requires_pr: false
+      success_requires_pr: ${{ needs.prepare.outputs.success_requires_pr == 'true' }}
       access_token_repos: ${{ github.repository }}
       require_access_token: true
       allowed_repos: '["${{ github.repository }}"]'
@@ -226,6 +253,8 @@ jobs:
       output_projections: ${{ needs.prepare.outputs.output_projections }}
       callback_data: ${{ needs.prepare.outputs.recipe_json }}
       run_agent: ${{ inputs.run_agent }}
+      dry_run: ${{ inputs.dry_run }}
     secrets:
-      ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      ACCESS_TOKEN: ${{ github.token }}
       EXTERNAL_PACKAGE_SOURCE_POLICY: ${{ secrets.EXTERNAL_PACKAGE_SOURCE_POLICY }}

README.md

@@ -38,19 +38,19 @@ jobs:
       docs_branch: docs-agent/my-repo-docs
       writable_paths: README.md,docs/**
     secrets:
-      ACCESS_TOKEN: ${{ secrets.DOCS_AGENT_ACCESS_TOKEN }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
       EXTERNAL_PACKAGE_SOURCE_POLICY: ${{ secrets.DOCS_AGENT_EXTERNAL_PACKAGE_SOURCE_POLICY }}
 ```
 
-`ACCESS_TOKEN` is required because the native runner checks out the target repository and may publish the Docs Agent branch and pull request. Docs Agent sets the target to the calling repository, so its normal consumer run is same-repository and the token must write that repository. Configure `DOCS_AGENT_ACCESS_TOKEN` with that access. `EXTERNAL_PACKAGE_SOURCE_POLICY` is a separate required secret: WP Codebox uses it only to authorize fetching the standalone Docs Agent package selected by the lane. A same-organization caller may instead use `secrets: inherit` when it defines both secrets. For a cross-organization call, map each secret explicitly as shown above.
+Docs Agent targets the calling repository and forwards its scoped `${{ github.token }}` to WP Codebox for checkout and publication. The consumer must grant `contents: write`, `pull-requests: write`, and `issues: write`; no `ACCESS_TOKEN` secret is required for this same-repository contract. `OPENAI_API_KEY` is optional in the reusable workflow schema but required for a live `run_agent: true` OpenAI run. `EXTERNAL_PACKAGE_SOURCE_POLICY` is a separate required secret: WP Codebox uses it only to authorize fetching the standalone Docs Agent package selected by the lane. Map both secrets explicitly, including for cross-organization calls.
 
 Configure `DOCS_AGENT_EXTERNAL_PACKAGE_SOURCE_POLICY` with this exact v1 JSON value:
 
 ```json
 {"version":1,"repositories":{"automattic/docs-agent":["bundles/technical-docs-agent/native/technical-docs-bootstrap-agent.agent.json","bundles/technical-docs-agent/native/technical-docs-maintenance-agent.agent.json","bundles/user-docs-agent/native/user-docs-bootstrap-agent.agent.json","bundles/user-docs-agent/native/user-docs-maintenance-agent.agent.json","bundles/skills-agent/native/skills-maintenance-agent.agent.json"]}}
 ```
 
-The policy authorizes only public `Automattic/docs-agent` package bytes. It does not grant target-repository publication access; keep `ACCESS_TOKEN` separate.
+The policy authorizes only public `Automattic/docs-agent` package bytes. It does not grant target-repository publication access.
 
 For repositories that run their own preflight detection, pass `run_agent: false` when no docs work is needed. The workflow records a deterministic skipped run instead of booting the agent runtime.
 
@@ -74,7 +74,7 @@ jobs:
       writable_paths: README.md,docs/**
       run_agent: ${{ needs.detect.outputs.should_run == 'true' }}
     secrets:
-      ACCESS_TOKEN: ${{ secrets.DOCS_AGENT_ACCESS_TOKEN }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
       EXTERNAL_PACKAGE_SOURCE_POLICY: ${{ secrets.DOCS_AGENT_EXTERNAL_PACKAGE_SOURCE_POLICY }}
 ```
 
@@ -85,13 +85,15 @@ The consumer API is product-level. Consumer repositories configure the documenta
 | Input | Default | Description |
 | --- | --- | --- |
 | `audience` | `technical` | `technical` for developer/operator docs, `user` for non-technical product docs, or `skills` for live skill upkeep. |
+| `run_kind` | `maintenance` | `bootstrap` establishes initial documentation and requires publication; `maintenance` permits a no-change result. |
 | `base_ref` | `main` | Base branch or ref for the maintenance PR. |
 | `docs_branch` | `docs-agent/docs-upkeep` | Stable branch reused for the canonical Docs Agent PR. |
 | `writable_paths` | `README.md,docs/**` | Comma-separated allowlist of paths Docs Agent may edit. |
 | `verification_commands` | `[]` | JSON array of canonical runner verification commands executed in the target workspace. |
 | `drift_checks` | `[]` | JSON array of canonical runner drift checks executed after verification. |
 | `prompt` | empty | Optional additional maintenance instruction. |
 | `run_agent` | `true` | Set `false` to skip after deterministic preflight says docs are current. |
+| `dry_run` | `false` | Set `true` to validate the prepared task without starting a live agent run. |
 
 `verification_commands` and `drift_checks` are executable runner inputs. Docs Agent keeps the target repository as the only writable PR boundary; the reusable runner executes the selected native agent task.
 
@@ -120,7 +122,7 @@ 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`, and bounded `projected_outputs_json` are exposed as reusable workflow outputs. A `run_agent: false` call returns `job_status: skipped`; it still requires the documented `ACCESS_TOKEN` mapping because the reusable workflow contract requires that secret. `projected_outputs_json` includes the runner publication URL when one exists; 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.
+- `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.
 
 ## Quality Bar
 
@@ -213,6 +215,9 @@ For skills PRs, also confirm the live instructions match current upstream tool b
 php tests/validate-docs-agent-bundle.php
 php tests/validate-external-native-package-sources.php
 php tests/repair-docs-links-smoke.php
+WP_CODEBOX_DIR=/path/to/wp-codebox php tests/validate-wp-codebox-run-agent-task-contract.php
+actionlint -config-file .github/actionlint.yaml .github/workflows/*.yml
+git diff --check
 ```
 
 The native import test uses the maintained Agents API pure-PHP smoke harness; clone `Automattic/agents-api` and run:

examples/consumer-workflow.yml

@@ -30,4 +30,6 @@ jobs:
       writable_paths: README.md,docs/**
       prompt: ${{ github.event_name == 'workflow_dispatch' && inputs.prompt || '' }}
       run_agent: ${{ github.event_name != 'workflow_dispatch' || inputs.run_agent }}
-    secrets: inherit
+    secrets:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      EXTERNAL_PACKAGE_SOURCE_POLICY: ${{ secrets.DOCS_AGENT_EXTERNAL_PACKAGE_SOURCE_POLICY }}