Give documentation runs enough agent turns

Author: chubes4

.github/workflows/maintain-docs.yml

@@ -69,6 +69,10 @@ env:
         description: Validate the prepared Docs Agent task without starting a live agent run.
         type: boolean
         default: false
+      max_turns:
+        description: Maximum agent turns available for repository discovery, documentation writes, and final diff inspection.
+        type: number
+        default: 32
     secrets:
       OPENAI_API_KEY:
         description: Optional OpenAI credential used for live Docs Agent runs.
@@ -364,6 +368,7 @@ jobs:
       artifact_declarations: ${{ needs.prepare.outputs.artifact_declarations }}
       output_projections: ${{ needs.prepare.outputs.output_projections }}
       callback_data: ${{ needs.prepare.outputs.recipe_json }}
+      max_turns: ${{ inputs.max_turns }}
       run_agent: ${{ inputs.run_agent }}
       dry_run: ${{ inputs.dry_run }}
     secrets:

tests/validate-docs-agent-packages.php

@@ -98,6 +98,8 @@
 $assert( str_contains( $maintain_docs_workflow, 'ACCESS_TOKEN: ${{ github.token }}' ), 'maintain-docs.yml must forward the caller-scoped GitHub token to the native runner.' );
 $assert( str_contains( $maintain_docs_workflow, 'EXTERNAL_PACKAGE_SOURCE_POLICY: ${{ secrets.EXTERNAL_PACKAGE_SOURCE_POLICY }}' ), 'maintain-docs.yml must explicitly forward the external package source policy.' );
 $assert( str_contains( $maintain_docs_workflow, 'runtime_sources: ${{ needs.prepare.outputs.runtime_sources }}' ), 'maintain-docs.yml must pass its complete native runtime closure to WP Codebox.' );
+$assert( str_contains( $maintain_docs_workflow, 'max_turns: ${{ inputs.max_turns }}' ), 'maintain-docs.yml must forward its documentation-sized turn budget to WP Codebox.' );
+$assert( 1 === preg_match( '/max_turns:\s*\n\s+description:.*\n\s+type: number\s*\n\s+default: 32/', $maintain_docs_workflow ), 'maintain-docs.yml must default to enough turns for bootstrap discovery, writes, and diff inspection.' );
 
 $workflow_readme = (string) file_get_contents( $root . '/.github/workflows/README.md' );
 foreach ( array( 'Docs Agent Runner Recipe', 'portable recipe', 'Docs Agent owns the native package' ) as $migration_note_text ) {

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

@@ -156,7 +156,7 @@
 	$input = $contract['inputs'][ $name ] ?? null;
 	$assert( is_array( $input ), "Docs Agent passes producer input {$name}, which is absent from the producer schema." );
 	$type = $input['type'] ?? null;
-	$actual_type = preg_match( '/^(true|false)$/', $value ) === 1 || in_array( $name, array( 'success_requires_pr', 'run_agent', 'dry_run' ), true ) ? 'boolean' : ( is_numeric( $value ) ? 'number' : 'string' );
+	$actual_type = preg_match( '/^(true|false)$/', $value ) === 1 || in_array( $name, array( 'success_requires_pr', 'run_agent', 'dry_run' ), true ) ? 'boolean' : ( is_numeric( $value ) || 'max_turns' === $name ? 'number' : 'string' );
 	$assert( $type === $actual_type, "Docs Agent input {$name} has {$actual_type} shape; producer requires {$type}." );
 }