Merge pull request #161 from Automattic/fix/160-drift-audit-contract

Require drift audit before maintenance no-op

Author: chubes4

.github/workflows/maintain-docs.yml

@@ -2,7 +2,7 @@ name: Maintain Docs
 
 env:
   # Advance this revision and all package digests together when package bytes change.
-  DOCS_AGENT_PACKAGE_REVISION: 7b2df969c34de112ec7ad13189ba94226a7f76f3
+  DOCS_AGENT_PACKAGE_REVISION: 85443eb91c12b2759d8e207f1ae4421407b4cc5e
 
 'on':
   workflow_call:
@@ -140,7 +140,7 @@ jobs:
             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"
+              package_digest="sha256-bytes-v1:78fef9f8d787866c7b48b8f044769d38c0528778c8e2a82af816f9f8ea65014f"
               lane_requires_pr=false
               default_prompt="Maintain source-grounded developer documentation that helps developers understand, use, and extend the code in the repository."
               ;;

README.md

@@ -191,7 +191,7 @@ Docs Agent has one canonical architecture: five standalone native Agents API pac
 - `bundles/user-docs-agent/native/user-docs-maintenance-agent.agent.json`
 - `bundles/skills-agent/native/skills-maintenance-agent.agent.json`
 
-These five `.agent.json` files are the complete executable package surface. Each package is the sole executable instruction authority for its lane. The reusable workflow maps `audience` and `run_kind` to exactly one package and its canonical agent slug; it does not select a separate manifest, flow, pipeline, or memory envelope. 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.
+These five `.agent.json` files are the complete executable package surface. Each package is the sole executable instruction authority for its lane. The reusable workflow maps `audience` and `run_kind` to exactly one package and its canonical agent slug; it does not select a separate manifest, flow, pipeline, or memory envelope. Every descriptor uses the package-source revision `85443eb91c12b2759d8e207f1ae4421407b4cc5e`, 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.
 

bundles/technical-docs-agent/native/technical-docs-maintenance-agent.agent.json

@@ -5,9 +5,9 @@
   "docsAgent": {
     "externalPackageSource": {
       "repository": "Automattic/docs-agent",
-      "revision": "7b2df969c34de112ec7ad13189ba94226a7f76f3",
+      "revision": "85443eb91c12b2759d8e207f1ae4421407b4cc5e",
       "path": "bundles/technical-docs-agent/native/technical-docs-maintenance-agent.agent.json",
-      "digest": "sha256-bytes-v1:6057aad4eb7c5f0320ccfbce9da93a5fa1d3fc521478b5571ed81c28129325aa"
+      "digest": "sha256-bytes-v1:78fef9f8d787866c7b48b8f044769d38c0528778c8e2a82af816f9f8ea65014f"
     },
     "agentSlug": "technical-docs-maintenance-agent"
   },

ci/docs-agent-runner-recipe.json

@@ -5,9 +5,9 @@
   "docsAgent": {
     "externalPackageSource": {
       "repository": "Automattic/docs-agent",
-      "revision": "7b2df969c34de112ec7ad13189ba94226a7f76f3",
+      "revision": "85443eb91c12b2759d8e207f1ae4421407b4cc5e",
       "path": "bundles/technical-docs-agent/native/technical-docs-maintenance-agent.agent.json",
-      "digest": "sha256-bytes-v1:6057aad4eb7c5f0320ccfbce9da93a5fa1d3fc521478b5571ed81c28129325aa"
+      "digest": "sha256-bytes-v1:78fef9f8d787866c7b48b8f044769d38c0528778c8e2a82af816f9f8ea65014f"
     },
     "agentSlug": "technical-docs-maintenance-agent"
   },

examples/runner-recipe.example.json

@@ -62,6 +62,14 @@
         "understand, use, and extend",
         "maintenance pass",
         "documentation drift",
+        "bounded source-vs-document drift audit",
+        "existing documentation claims",
+        "configuration and workflow behavior",
+        "immutable revisions and provenance",
+        "commands, tests, examples, and operational contracts",
+        "every audited claim matches source",
+        "smallest reviewable documentation correction",
+        "runner-enforced writable path scope",
         "no_changes",
         "provided workspace",
         "workspace_git_status",

tests/native-agent.validate-package-spec.json

@@ -3,5 +3,5 @@
   "called_workflow_context": {
     "job_workflow_sha": ""
   },
-  "expected_package_revision": "7b2df969c34de112ec7ad13189ba94226a7f76f3"
+  "expected_package_revision": "85443eb91c12b2759d8e207f1ae4421407b4cc5e"
 }

tests/reusable-workflow-empty-called-workflow-context.fixture.json

@@ -44,9 +44,9 @@
 $assert( 'docs-agent/runner-recipe/v1' === ( $recipe['schema'] ?? null ), 'Runner recipe must use the portable Docs Agent runner recipe schema.' );
 $expected_package_source = array(
 	'repository' => 'Automattic/docs-agent',
-	'revision'   => '7b2df969c34de112ec7ad13189ba94226a7f76f3',
+	'revision'   => '85443eb91c12b2759d8e207f1ae4421407b4cc5e',
 	'path'       => 'bundles/technical-docs-agent/native/technical-docs-maintenance-agent.agent.json',
-	'digest'     => 'sha256-bytes-v1:6057aad4eb7c5f0320ccfbce9da93a5fa1d3fc521478b5571ed81c28129325aa',
+	'digest'     => 'sha256-bytes-v1:78fef9f8d787866c7b48b8f044769d38c0528778c8e2a82af816f9f8ea65014f',
 );
 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.' );

tests/validate-docs-agent-packages.php

@@ -30,10 +30,10 @@
 	return $contents;
 };
 
-$package_revision = '7b2df969c34de112ec7ad13189ba94226a7f76f3';
+$package_revision = '85443eb91c12b2759d8e207f1ae4421407b4cc5e';
 $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' ),
+	'technical:maintenance' => array( 'path' => 'bundles/technical-docs-agent/native/technical-docs-maintenance-agent.agent.json', 'slug' => 'technical-docs-maintenance-agent', 'digest' => '78fef9f8d787866c7b48b8f044769d38c0528778c8e2a82af816f9f8ea65014f' ),
 	'user:bootstrap'      => array( 'path' => 'bundles/user-docs-agent/native/user-docs-bootstrap-agent.agent.json', 'slug' => 'user-docs-bootstrap-agent', 'digest' => 'ee558a73f2a393c1912d62f7f40dbdd4bc31ac0168c3c248316b3430258c55cd' ),
 	'user:maintenance'    => array( 'path' => 'bundles/user-docs-agent/native/user-docs-maintenance-agent.agent.json', 'slug' => 'user-docs-maintenance-agent', 'digest' => 'e2248f014c1409a8d4c5cb303ea37c0b24ae05babd02d40c6032160daf60d4c4' ),
 	'skills:maintenance'  => array( 'path' => 'bundles/skills-agent/native/skills-maintenance-agent.agent.json', 'slug' => 'skills-maintenance-agent', 'digest' => 'c643f8bd31864cdd607f9025a000694a65a3fdf91532e4311fbac541e708a2b2' ),

tests/validate-external-native-package-sources.php

@@ -224,7 +224,7 @@
 
 $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, 'DOCS_AGENT_PACKAGE_REVISION: 85443eb91c12b2759d8e207f1ae4421407b4cc5e' ), '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( "/runtime_sources='(?<json>[^']+)'/", $workflow, $runtime_sources_match );