Pin Docs Agent native package source revision (#122)

chubes4 · web-flow · commit d054c3782337 · 2026-07-13T16:12:09.000-04:00
diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
@@ -16,7 +16,7 @@ The target repository grants `contents: write`, `pull-requests: write`, and `iss
 
 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, workspace publication expectations, artifact declarations, verification, drift checks, and output mapping suggestions. Package provenance is the immutable reusable-workflow commit and each descriptor includes a byte digest. Runtime substrate checkout resolution is intentionally outside the Docs Agent-facing recipe, and validation blocks concrete runner workflow calls, runtime ability names, component paths, mount directives, provider defaults, and define directives from consumer examples.
+The recipe boundary covers standalone native package 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. Runtime substrate checkout resolution is intentionally outside the Docs Agent-facing recipe, and validation blocks concrete runner workflow calls, runtime ability names, component paths, mount directives, provider defaults, and define directives from consumer examples.
 
 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.
 
diff --git a/.github/workflows/maintain-docs.yml b/.github/workflows/maintain-docs.yml
@@ -1,5 +1,9 @@
 name: Maintain Docs
 
+env:
+  # Advance this revision and all package digests together when package bytes change.
+  DOCS_AGENT_PACKAGE_REVISION: 7b2df969c34de112ec7ad13189ba94226a7f76f3
+
 'on':
   workflow_call:
     inputs:
@@ -102,7 +106,6 @@ jobs:
           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 }}
           GITHUB_REPOSITORY_NAME: ${{ github.repository }}
@@ -160,8 +163,8 @@ jobs:
 
           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
-            printf 'github.job_workflow_sha must be a full immutable Docs Agent commit SHA.\n' >&2
+          if ! printf '%s' "$DOCS_AGENT_PACKAGE_REVISION" | grep -Eq '^[0-9a-fA-F]{40}$'; then
+            printf 'DOCS_AGENT_PACKAGE_REVISION must be a full immutable Docs Agent commit SHA.\n' >&2
             exit 1
           fi
 
@@ -190,7 +193,7 @@ jobs:
             --arg targetRepository "$GITHUB_REPOSITORY_NAME" \
             --arg prompt "$prompt" \
             --arg repository "Automattic/docs-agent" \
-            --arg revision "$DOCS_AGENT_REVISION" \
+            --arg revision "$DOCS_AGENT_PACKAGE_REVISION" \
             --arg packagePath "$package_path" \
             --arg packageDigest "$package_digest" \
             --arg agentSlug "$agent_slug" \
@@ -202,7 +205,7 @@ jobs:
             --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}}')"
-          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}')"
+          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}')"
 
           runner_workspace="$(jq -cn \
             --arg repo "$GITHUB_REPOSITORY_NAME" \
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -17,6 +17,7 @@ jobs:
         with:
           repository: Automattic/docs-agent
           ref: ${{ github.sha }}
+          fetch-depth: 0
           persist-credentials: false
 
       - name: Check out Agents API
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -11,6 +11,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - name: Checkout WP Codebox producer contract
         uses: actions/checkout@v4
         with:
diff --git a/README.md b/README.md
@@ -187,7 +187,9 @@ Docs Agent ships standalone native Agents API packages selected by the reusable
 - `bundles/user-docs-agent/native/user-docs-maintenance-agent.agent.json`
 - `bundles/skills-agent/native/skills-maintenance-agent.agent.json`
 
-The reusable workflow maps `audience` and `run_kind` to exactly one package and its canonical agent slug. It pins the source to `github.job_workflow_sha`, the immutable commit GitHub used for the called reusable workflow, rejects a missing or non-SHA value, and supplies a byte-level `sha256-bytes-v1` digest.
+The reusable workflow maps `audience` and `run_kind` to exactly one package and its canonical agent slug. Every descriptor uses the package-source revision `7b2df969c34de112ec7ad13189ba94226a7f76f3`, independently of the revision that invokes the reusable workflow, and supplies a byte-level `sha256-bytes-v1` digest.
+
+Package updates advance the package-source revision and all five declared digests atomically. The immutable-source validator reads each package blob from that Git revision, recomputes its digest and canonical slug, and rejects a descriptor that does not match those historical bytes.
 
 Each lane also ships native Agents API runtime packages for direct import through `wp_agent_import_runtime_bundles()`: technical docs bootstrap and maintenance, user docs bootstrap and maintenance, and skills maintenance. These packages retain the same source-grounded workspace-only editing boundary and required workspace-write gate as their corresponding bundle lanes.
 
@@ -216,7 +218,7 @@ 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
+actionlint .github/workflows/*.yml
 git diff --check
 ```
 
@@ -228,4 +230,4 @@ AGENTS_API_DIR=/path/to/agents-api php tests/native-agent-import.php
 
 It imports every native package through `wp_agent_import_runtime_bundles()`, verifies registration and preserved write-gate defaults, and invokes the default native chat handler far enough to resolve each registered agent. It intentionally fails when `AGENTS_API_DIR` is unavailable rather than treating an unexecuted importer as a passing test. It does not execute a model turn because the packages intentionally leave provider/model selection to the caller.
 
-The `Docs Agent Tests` GitHub Actions workflow runs on pull requests and pushes. It runs the structural bundle validator, native package descriptor/digest validator, docs-link repair smoke test, and native importer integration test against `Automattic/agents-api` at `5addf598167ec17821954b0f9aa3a9b160b7e36e`.
+The `Docs Agent Tests` GitHub Actions workflow runs on pull requests and pushes. It fetches Docs Agent history so it can run the immutable native package source validator, then runs the structural bundle validator, docs-link repair smoke test, and native importer integration test against `Automattic/agents-api` at `5addf598167ec17821954b0f9aa3a9b160b7e36e`.
diff --git a/ci/docs-agent-runner-recipe.json b/ci/docs-agent-runner-recipe.json
@@ -3,13 +3,13 @@
   "targetRepository": "OWNER/REPO",
   "prompt": "Run the technical docs maintenance flow. Update developer-facing living documentation only where source evidence shows stale, missing, fragmented, or misleading coverage.",
   "docsAgent": {
-    "repository": "https://github.com/Automattic/docs-agent.git",
-    "ref": "main",
-    "bundlePath": "bundles/technical-docs-agent",
-    "bundlePathInRepo": "bundles/technical-docs-agent",
-    "agentSlug": "technical-docs-agent",
-    "pipelineSlug": "technical-docs-pipeline",
-    "flowSlug": "technical-docs-maintenance-flow"
+    "externalPackageSource": {
+      "repository": "Automattic/docs-agent",
+      "revision": "7b2df969c34de112ec7ad13189ba94226a7f76f3",
+      "path": "bundles/technical-docs-agent/native/technical-docs-maintenance-agent.agent.json",
+      "digest": "sha256-bytes-v1:6057aad4eb7c5f0320ccfbce9da93a5fa1d3fc521478b5571ed81c28129325aa"
+    },
+    "agentSlug": "technical-docs-maintenance-agent"
   },
   "runner": {
     "verificationCommands": [],
diff --git a/examples/runner-recipe.example.json b/examples/runner-recipe.example.json
@@ -3,13 +3,13 @@
   "targetRepository": "OWNER/REPO",
   "prompt": "Run the technical docs maintenance flow. Update developer-facing living documentation only where source evidence shows stale, missing, fragmented, or misleading coverage.",
   "docsAgent": {
-    "repository": "https://github.com/Automattic/docs-agent.git",
-    "ref": "v0.1.0",
-    "bundlePath": "bundles/technical-docs-agent",
-    "bundlePathInRepo": "bundles/technical-docs-agent",
-    "agentSlug": "technical-docs-agent",
-    "pipelineSlug": "technical-docs-pipeline",
-    "flowSlug": "technical-docs-maintenance-flow"
+    "externalPackageSource": {
+      "repository": "Automattic/docs-agent",
+      "revision": "7b2df969c34de112ec7ad13189ba94226a7f76f3",
+      "path": "bundles/technical-docs-agent/native/technical-docs-maintenance-agent.agent.json",
+      "digest": "sha256-bytes-v1:6057aad4eb7c5f0320ccfbce9da93a5fa1d3fc521478b5571ed81c28129325aa"
+    },
+    "agentSlug": "technical-docs-maintenance-agent"
   },
   "runner": {
     "verificationCommands": [],
diff --git a/tests/reusable-workflow-empty-called-workflow-context.fixture.json b/tests/reusable-workflow-empty-called-workflow-context.fixture.json
@@ -0,0 +1,7 @@
+{
+  "failed_runs": [29280583288, 29280583450, 29280583504, 29280583286],
+  "called_workflow_context": {
+    "job_workflow_sha": ""
+  },
+  "expected_package_revision": "7b2df969c34de112ec7ad13189ba94226a7f76f3"
+}
diff --git a/tests/validate-docs-agent-bundle.php b/tests/validate-docs-agent-bundle.php
@@ -149,7 +149,16 @@
 
 $assert( 'docs-agent/runner-recipe/v1' === ( $example['schema'] ?? null ), 'Example config must use the portable Docs Agent runner recipe schema.' );
 $assert( 'docs-agent/runner-recipe/v1' === ( $recipe['schema'] ?? null ), 'Runner recipe must use the portable Docs Agent runner recipe schema.' );
-$assert( 'https://github.com/Automattic/docs-agent.git' === ( $example['docsAgent']['repository'] ?? null ), 'Example config must point docsAgent.repository at Docs Agent.' );
+$expected_package_source = array(
+	'repository' => 'Automattic/docs-agent',
+	'revision'   => '7b2df969c34de112ec7ad13189ba94226a7f76f3',
+	'path'       => 'bundles/technical-docs-agent/native/technical-docs-maintenance-agent.agent.json',
+	'digest'     => 'sha256-bytes-v1:6057aad4eb7c5f0320ccfbce9da93a5fa1d3fc521478b5571ed81c28129325aa',
+);
+foreach ( array( $recipe, $example ) as $runner_recipe ) {
+	$assert( $expected_package_source === ( $runner_recipe['docsAgent']['externalPackageSource'] ?? null ), 'Runner recipes must use the immutable Docs Agent package source.' );
+	$assert( 'technical-docs-maintenance-agent' === ( $runner_recipe['docsAgent']['agentSlug'] ?? null ), 'Runner recipes must use the package agent slug.' );
+}
 
 $recipe_text = (string) file_get_contents( $root . '/ci/docs-agent-runner-recipe.json' );
 $blocked_runtime_fragments = array( 'wp-codebox', 'Automattic/wp-codebox', 'Extra-Chill/homeboy', 'homeboy-extensions', 'datamachine/', 'datamachine-agent-ci', 'runtime_task_ability', 'runtime_bundle_ability', 'runtime_workflow_ability', 'runtime_components', 'Automattic/agents-api@', 'Extra-Chill/data-machine@', 'Extra-Chill/data-machine-code@', 'workspace_policy', '/wordpress/wp-content/mu-plugins', 'required_abilities', 'disable_datamachine_directives', 'provider: openai', 'OPENAI_API_KEY', 'default_provider', 'default_model' );
diff --git a/tests/validate-external-native-package-sources.php b/tests/validate-external-native-package-sources.php
@@ -16,6 +16,21 @@
 	}
 };
 
+$read_revision_package = static function ( string $revision, string $path ) use ( $root ): string {
+	$command = sprintf(
+		'git -C %s show %s',
+		escapeshellarg( $root ),
+		escapeshellarg( $revision . ':' . $path )
+	);
+	$contents = shell_exec( $command );
+	if ( ! is_string( $contents ) || '' === $contents ) {
+		throw new RuntimeException( "Unable to read {$path} from immutable revision {$revision}." );
+	}
+
+	return $contents;
+};
+
+$package_revision = '7b2df969c34de112ec7ad13189ba94226a7f76f3';
 $packages = array(
 	'technical:bootstrap' => array( 'path' => 'bundles/technical-docs-agent/native/technical-docs-bootstrap-agent.agent.json', 'slug' => 'technical-docs-bootstrap-agent', 'digest' => '9050c9b4364a5a91b057fd51ff5f667efc320f9d6776160ab3e7cf4fd5e4f0e6' ),
 	'technical:maintenance' => array( 'path' => 'bundles/technical-docs-agent/native/technical-docs-maintenance-agent.agent.json', 'slug' => 'technical-docs-maintenance-agent', 'digest' => '6057aad4eb7c5f0320ccfbce9da93a5fa1d3fc521478b5571ed81c28129325aa' ),
@@ -25,12 +40,11 @@
 );
 
 foreach ( $packages as $lane => $package ) {
-	$path = $root . '/' . $package['path'];
-	$assert( is_file( $path ), "{$lane} package is missing." );
-	$document = json_decode( (string) file_get_contents( $path ), true );
+	$contents = $read_revision_package( $package_revision, $package['path'] );
+	$document = json_decode( $contents, true );
 	$assert( is_array( $document ), "{$lane} package is invalid JSON." );
 	$assert( $package['slug'] === ( $document['agent']['agent_slug'] ?? null ), "{$lane} descriptor must use the package's canonical agent slug." );
-	$assert( $package['digest'] === hash_file( 'sha256', $path ), "{$lane} descriptor digest does not match package bytes." );
+	$assert( $package['digest'] === hash( 'sha256', $contents ), "{$lane} descriptor digest does not match immutable package bytes." );
 
 	$case = preg_quote( $lane . ')', '/' );
 	$pattern = '/case "\$AUDIENCE:\$RUN_KIND" in.*?' . $case . '(?<body>.*?);;(?=\n            )/s';
@@ -41,8 +55,18 @@
 	$assert( str_contains( $body, 'package_digest="sha256-bytes-v1:' . $package['digest'] . '"' ), "{$lane} must map to its byte digest." );
 }
 
-$assert( str_contains( $workflow, 'DOCS_AGENT_REVISION: ${{ github.job_workflow_sha }}' ), 'The external source revision must come from github.job_workflow_sha.' );
+$fixture = json_decode( (string) file_get_contents( $root . '/tests/reusable-workflow-empty-called-workflow-context.fixture.json' ), true );
+$assert( is_array( $fixture ), 'The empty called-workflow context fixture must be valid JSON.' );
+$assert( array( 29280583288, 29280583450, 29280583504, 29280583286 ) === ( $fixture['failed_runs'] ?? null ), 'The regression fixture must retain all failed consumer runs.' );
+$assert( '' === ( $fixture['called_workflow_context']['job_workflow_sha'] ?? null ), 'The regression fixture must model the empty called-workflow SHA.' );
+$assert( $package_revision === ( $fixture['expected_package_revision'] ?? null ), 'An empty called-workflow context must prepare the fixed package revision.' );
+
+$assert( str_contains( $workflow, 'DOCS_AGENT_PACKAGE_REVISION: ' . $package_revision ), 'The workflow must define the immutable package revision once.' );
+$assert( str_contains( $workflow, '--arg revision "$DOCS_AGENT_PACKAGE_REVISION"' ), 'The recipe must use the immutable package revision.' );
+$assert( str_contains( $workflow, '--arg revision "$DOCS_AGENT_PACKAGE_REVISION" --arg path "$package_path"' ), 'The runner descriptor must use the immutable package revision.' );
+$assert( ! str_contains( $workflow, 'github.job_workflow_sha' ), 'Recipe preparation must not depend on the called-workflow SHA.' );
 $assert( ! str_contains( $workflow, 'github.workflow_sha' ), 'The external source revision must not use the consumer workflow SHA.' );
+$assert( ! str_contains( $workflow, 'DOCS_AGENT_REVISION' ), 'The workflow must use the package-source revision name consistently.' );
 $assert( str_contains( $workflow, "grep -Eq '^[0-9a-fA-F]{40}\$'" ), 'The workflow must fail closed when the source revision is not a full SHA.' );
 $assert( str_contains( $workflow, 'external_package_source: ${{ needs.prepare.outputs.external_package_source }}' ), 'The native runner must receive the descriptor output.' );
 $assert( ! str_contains( $workflow, 'agent_bundle:' ), 'The active workflow must not pass a legacy agent bundle.' );
diff --git a/tests/validate-wp-codebox-run-agent-task-contract.php b/tests/validate-wp-codebox-run-agent-task-contract.php
@@ -120,6 +120,8 @@
 
 $assert( isset( $caller_inputs['external_package_source'] ), 'Docs Agent must provide the required external package descriptor.' );
 $assert( ! isset( $caller_inputs['agent_bundle'] ), 'Docs Agent must not pass the removed agent_bundle input.' );
+$assert( str_contains( $workflow, 'DOCS_AGENT_PACKAGE_REVISION: 7b2df969c34de112ec7ad13189ba94226a7f76f3' ), 'Docs Agent must use the fixed native package source revision.' );
+$assert( ! str_contains( $workflow, 'github.job_workflow_sha' ), 'Docs Agent must not depend on unavailable called-workflow provenance.' );
 
 preg_match( "/output_projections='(?<json>[^']+)'/", $workflow, $projection_match );
 $assert( isset( $projection_match['json'] ), 'Docs Agent must define output projections for the producer.' );
