Enforce native Docs Agent completion outcomes (#167)

* Enforce native Docs Agent completion outcomes

* Advance native completion contract provenance

* Harden completion report validation

* Publish validated completion reports

* Pin completion contract provenance

* Pin accepted WP Codebox producer

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`, `require_pr`, `base_ref`, `docs_branch`, `writable_paths`, `validation_dependencies`, `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`, `require_pr`, `base_ref`, `docs_branch`, `writable_paths`, `context_repositories`, `bootstrap_contract`, `source_delta`, `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.
 
@@ -10,13 +10,13 @@ Schedule skills upkeep separately from docs upkeep. The skills lane should use a
 
 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.
 
-Maintenance permits a no-op by default. Set `require_pr: true` for an acceptance or remediation run that must produce a valid target-repository PR; bootstrap always requires publication.
+Maintenance permits an evidence-backed no-op only for a non-empty caller-bounded `source_delta`. Every delta item must have source refs and a matching evidence-backed report item that covers them; exactly one versioned report from the canonical native transcript must agree with the host diff. Bootstrap may instead use inventory mode with its positive contract. Set `require_pr: true` for changed maintenance that must produce a valid target-repository PR; bootstrap changes always require publication.
 
-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 reusable workflow declares the expected typed review artifacts for Docs Agent runs: transcript, change summary, verification report, drift report, completion 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 completion runtime declaration remains optional for producer lifecycle compatibility, but the final completion drift command has a mandatory generic `{name,type,path}` artifact output. The Docs Agent-owned validator reads the report from the canonical transcript, compares it with the applied host diff, writes canonical bytes under `.codebox/agent-task-artifacts`, and WP Codebox stages only that validated declared artifact for review.
 
 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.29](https://github.com/Automattic/wp-codebox/releases/tag/v0.12.29) workflow and passes the matching `wp_codebox_release_ref: v0.12.29` input. The release tag resolves to immutable revision `bc982947ec33c78160125026e16d357b7ece3ea1`, which is distinct from the fixed Docs Agent package revision. WP Codebox validates the paired tags, materializes the declared native runtime closure, executes the selected package, applies bounded workspace changes, runs verification, and publishes approved host changes. Its published assets are `01-wp-codebox.zip` and `02-wp-codebox-workspace-0.12.29.tgz`; the private package-recovery manifest is intentionally not a reviewer asset.
+Docs Agent consumes the reusable WP Codebox workflow at accepted immutable revision `12a5bb19a97b89d0a78b502fc71adede5b122359` and passes `wp_codebox_release_ref: v0.12.29` only for released packaged runtime assets. The release tag resolves to immutable revision `bc982947ec33c78160125026e16d357b7ece3ea1`, distinct from both the workflow producer revision and the fixed Docs Agent package revision. WP Codebox materializes the declared native runtime closure, executes the selected package, applies bounded workspace changes, runs verification, and publishes approved host changes. The released assets are `01-wp-codebox.zip` and `02-wp-codebox-workspace-0.12.29.tgz`; the private package-recovery manifest is intentionally not a reviewer asset.
 
 Provider artifacts retain only allowlisted review artifacts, controlled workflow envelopes, and canonical runtime-source and seed provenance. WP Codebox v0.12.24 uploads a reviewer-safe workflow-result projection: public control, verification, publication, output-projection, access, failure, artifact-declaration, and canonical transcript-provenance fields remain, while raw `runtime_result`, `outputs.engine_data`, model/provider/tool payloads, source content, private paths, and secrets are excluded. Before persistence or upload, it sanitizes private runtime paths from nested values, object keys, diagnostics, and command arguments. WP Codebox captures one trusted canonical `codebox-transcript` through a pre-sanitization reviewer-evidence descriptor, validates its artifact-root containment, schema, digest, and size, then emits the compact reviewer transcript as a `wp-codebox/reviewer-agent-transcript/v1` projection. Before apply-back, it compares the seed identity with the host workspace identity; rejected patches preserve the expected and actual identities plus patch and changed-file evidence for upload. Its pre-redaction trusted apply input preserves machine-applicable patch bytes in a private channel that is removed before durable artifact sanitization, as fixed in [WP Codebox #1842](https://github.com/Automattic/wp-codebox/pull/1842). The canonical transcript remains the bounded tool-observability surface. Lifecycle and downstream failures retain runtime evidence in their internal normalized failed result even when artifact preparation cannot complete. Diagnostic messages that name runtime classes remain reviewable, while PHP-shaped runtime source remains blocked. See [WP Codebox #1767](https://github.com/Automattic/wp-codebox/issues/1767), [WP Codebox #1814](https://github.com/Automattic/wp-codebox/issues/1814), [WP Codebox #1815](https://github.com/Automattic/wp-codebox/pull/1815), and [WP Codebox #1823](https://github.com/Automattic/wp-codebox/pull/1823). Successful canonical reviewer-evidence reference: [run `29350690551`](https://github.com/Automattic/build-with-wordpress/actions/runs/29350690551). The [hosted failure `29468956857`](https://github.com/Automattic/agents-api/actions/runs/29468956857) executed WP Codebox v0.12.20, published [Agents API #430](https://github.com/Automattic/agents-api/pull/430), then failed during upload preparation; it motivated #1814/#1815 and is not a successful v0.12.24 reviewer-safe workflow-result run.
 
@@ -34,10 +34,12 @@ WP Codebox v0.12.29 returns `{ valid: true }` without a failure-only `error` whe
 
 Docs Agent workflow call sites prepare a portable recipe instead of calling a concrete runner. Docs Agent owns the native package, lane, artifact, prompt, and workspace mapping. Consumers depend on Docs Agent inputs and review artifacts, not runner internals.
 
-The recipe boundary covers standalone native package selection, complete native runtime closure selection, workspace publication expectations, artifact declarations, verification, drift checks, and output mapping suggestions. Package provenance is the fixed `DOCS_AGENT_PACKAGE_REVISION`, independent of the reusable-workflow revision, and each descriptor includes a byte digest. Package changes advance that revision and every declared digest atomically. Docs Agent declares the runtime sources; WP Codebox materializes and lowers them under its generic runtime contract.
+The recipe boundary covers standalone native package selection, complete native runtime closure selection, read-only context repositories, bootstrap criteria, bounded source deltas, workspace publication expectations, artifact declarations, verification, drift checks, and output mapping suggestions. Package provenance is the fixed `DOCS_AGENT_PACKAGE_REVISION`, independent of the reusable-workflow revision, and each descriptor includes a byte digest. Package changes advance that revision and every declared digest atomically. The post-command validator has its own immutable `DOCS_AGENT_COMPLETION_CONTRACT_REVISION`, so validator changes do not rewrite unchanged package provenance. Docs Agent declares the runtime sources and product completion check. WP Codebox materializes and lowers them under its generic runtime contract, including its generic command interface, without learning Docs Agent semantics.
+
+The execution order is native package runtime, host patch apply, caller dependency command, caller verification commands, caller drift checks, Docs Agent completion validation and command-artifact capture, publication, then WP Codebox declared-artifact staging and upload. This makes the validated report reviewer-visible without moving Docs Agent semantics into the producer. Neither WP Codebox nor Agents API implements Docs Agent report fields or outcome rules, and Data Machine is not part of the path.
 
 Native package selection is expressed through recipe `docsAgent.externalPackageSource`. Workspace boundaries are expressed through recipe `runner` fields so agents remain workspace editors while caller-owned execution handles sandboxing and publication handoff.
 
-Direct consumers of the removed legacy manifests, flows, pipelines, or memory envelopes must migrate to the corresponding native `.agent.json` package. Existing `maintain-docs.yml` consumers already select native packages and are unaffected.
+Direct consumers of the removed legacy manifests, flows, pipelines, or memory envelopes must migrate to the corresponding native `.agent.json` package. Existing `maintain-docs.yml` consumers retain native execution, but maintenance calls now require non-empty caller-bounded source deltas and bootstrap calls must provide positive `bootstrap_contract` criteria.
 
 Run `php tests/validate-docs-agent-packages.php` after workflow changes so package structure, workflow routing, and runner config stay aligned.