@agent-teams/docs-protocol 0.1.0-rc.1 → 0.1.0-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-teams/docs-protocol",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.2",
   "description": "Unified deterministic documentation authoring protocol for Agent Teams repositories.",
   "license": "Apache-2.0",
   "type": "module",
@@ -25,6 +25,13 @@
     "schemas/docs-protocol/v1.schema.json",
     "schemas/docs-protocol-profile/v1.schema.json",
     "schemas/docs-protocol-command-envelope/v1.schema.json",
+    "schemas/docs-consumer-integration-execution/v1.schema.json",
+    "schemas/docs-consumer-integration-plan/v1.schema.json",
+    "schemas/docs-consumer-integration-profile/v1.schema.json",
+    "schemas/docs-consumer-managed-state/v1.schema.json",
+    "schemas/qualified-docs-cohort/v1.schema.json",
+    "skills/docs/SKILL.md",
+    "assets",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -50,15 +57,18 @@
   "dependencies": {
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
+    "jsonc-parser": "3.3.1",
     "yaml": "2.9.0",
-    "@agent-teams/engineering-foundation": "0.17.0-rc.0"
+    "@agent-teams/engineering-foundation": "0.17.0-rc.1"
   },
   "devDependencies": {
     "@types/node": "24.13.3",
     "typescript": "7.0.2"
   },
   "scripts": {
-    "build": "tsc --build tsconfig.json --pretty false",
+    "assets:generate": "node scripts/generate-consumer-assets.mjs --write",
+    "assets:check": "node scripts/generate-consumer-assets.mjs",
+    "build": "pnpm assets:check && tsc --build tsconfig.json --pretty false",
     "test": "pnpm build && node --test tests/*.test.mjs"
   }
 }

package/schemas/docs-consumer-integration-execution/v1.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-consumer-integration-execution/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "command", "outcome", "issues"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "command": { "enum": ["consumer.apply", "consumer.check", "consumer.plan", "consumer.recover"] },
+    "outcome": { "enum": ["applied", "blocked", "change-required", "current", "recovered"] },
+    "issues": {
+      "type": "array",
+      "maxItems": 64,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "severity", "subject", "message"],
+        "properties": {
+          "code": { "type": "string", "pattern": "^[A-Z0-9_]+$", "maxLength": 128 },
+          "severity": { "enum": ["error", "warning"] },
+          "subject": { "type": "string", "maxLength": 2048 },
+          "message": { "type": "string", "maxLength": 4096 }
+        }
+      }
+    },
+    "plan": { "$ref": "https://agent-teams.ai/schemas/docs-consumer-integration-plan/v1" },
+    "receipt": { "$ref": "https://agent-teams.ai/schemas/known-file-transaction-receipt/v1" }
+  }
+}

package/schemas/docs-consumer-integration-plan/v1.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-consumer-integration-plan/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "cohortId", "repository", "planDigest", "outcome", "assets", "issues"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "cohortId": { "type": "string", "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$" },
+    "repository": { "$ref": "#/$defs/repository" },
+    "planDigest": { "$ref": "#/$defs/sha256" },
+    "outcome": { "enum": ["blocked", "change-required", "current"] },
+    "assets": {
+      "type": "array",
+      "minItems": 5,
+      "maxItems": 5,
+      "items": { "$ref": "#/$defs/asset" }
+    },
+    "issues": {
+      "type": "array",
+      "maxItems": 64,
+      "items": { "$ref": "#/$defs/issue" }
+    }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "id", "nameWithOwner"],
+      "properties": {
+        "provider": { "const": "github" },
+        "id": { "type": "string", "pattern": "^[1-9][0-9]*$" },
+        "nameWithOwner": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" }
+      }
+    },
+    "asset": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "path", "ownership", "state", "expectedDigest", "action"],
+      "properties": {
+        "id": { "enum": ["agents-route", "caller-workflow", "managed-state", "package-manifest", "skill"] },
+        "path": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "ownership": { "enum": ["full-bytes", "partial-fields", "managed-block"] },
+        "state": { "enum": ["absent", "exact-current", "known-prior", "partial-adoption", "outdated-cohort", "unknown-modified", "conflict", "unsupported"] },
+        "currentDigest": { "$ref": "#/$defs/sha256" },
+        "expectedDigest": { "$ref": "#/$defs/sha256" },
+        "action": { "enum": ["create", "none", "replace", "blocked"] }
+      }
+    },
+    "issue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "severity", "subject", "message"],
+      "properties": {
+        "code": { "type": "string", "pattern": "^[A-Z0-9_]+$", "maxLength": 128 },
+        "severity": { "enum": ["error", "warning"] },
+        "subject": { "type": "string", "maxLength": 2048 },
+        "message": { "type": "string", "maxLength": 4096 }
+      }
+    }
+  }
+}

package/schemas/docs-consumer-integration-profile/v1.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-consumer-integration-profile/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "repository", "integrationRoot", "packageManager", "profilePath", "skillPath", "callerWorkflowPath", "managedStatePath", "cohort"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "id", "nameWithOwner"],
+      "properties": {
+        "provider": { "const": "github" },
+        "id": { "type": "string", "pattern": "^[1-9][0-9]*$" },
+        "nameWithOwner": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" }
+      }
+    },
+    "integrationRoot": { "const": "." },
+    "packageManager": { "const": "pnpm" },
+    "profilePath": { "const": "architecture/foundation/docs-protocol.yaml" },
+    "skillPath": { "const": ".agents/skills/docs-authoring/SKILL.md" },
+    "callerWorkflowPath": { "const": ".github/workflows/docs-protocol.yml" },
+    "managedStatePath": { "const": "architecture/foundation/docs-protocol-managed-state.json" },
+    "governedDocsRoots": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 32,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._@-]{1,255}(?:/[A-Za-z0-9._@-]{1,255})*$" }
+    },
+    "cohort": { "$ref": "#/$defs/cohortBinding" }
+  },
+  "$defs": {
+    "cohortBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "cohortId", "channel", "recordDigest", "qualificationEventDigest", "eligibleAfter", "upgradeFrom", "rollbackTo", "packages", "workflow", "assets", "schemas", "runtime"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "cohortId": { "type": "string", "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$" },
+        "channel": { "enum": ["rc", "stable"] },
+        "recordDigest": { "$ref": "#/$defs/nonzeroSha256" },
+        "qualificationEventDigest": { "$ref": "#/$defs/nonzeroSha256" },
+        "eligibleAfter": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$" },
+        "upgradeFrom": { "$ref": "#/$defs/cohortIds" },
+        "rollbackTo": { "$ref": "#/$defs/cohortIds" },
+        "packages": {
+          "type": "object", "additionalProperties": false,
+          "required": ["docsProtocol", "engineeringFoundation"],
+          "properties": {
+            "docsProtocol": { "$ref": "#/$defs/package" },
+            "engineeringFoundation": { "$ref": "#/$defs/package" }
+          }
+        },
+        "workflow": {
+          "type": "object", "additionalProperties": false,
+          "required": ["repository", "path", "revision", "blobSha"],
+          "properties": {
+            "repository": { "const": "agent-teams-ai/.github" },
+            "path": { "const": ".github/workflows/docs-protocol-check.yml" },
+            "revision": { "type": "string", "pattern": "^(?!0{40}$)[0-9a-f]{40}$" },
+            "blobSha": { "type": "string", "pattern": "^(?!0{40}$)[0-9a-f]{40}$" }
+          }
+        },
+        "assets": {
+          "type": "object", "additionalProperties": false,
+          "required": ["skillDigest", "callerWorkflowDigest", "assetCatalogDigest", "transitionCatalogDigest"],
+          "properties": {
+            "skillDigest": { "$ref": "#/$defs/nonzeroSha256" },
+            "callerWorkflowDigest": { "$ref": "#/$defs/nonzeroSha256" },
+            "assetCatalogDigest": { "$ref": "#/$defs/nonzeroSha256" },
+            "transitionCatalogDigest": { "$ref": "#/$defs/nonzeroSha256" }
+          }
+        },
+        "schemas": {
+          "type": "object", "additionalProperties": false,
+          "required": ["consumerIntegration", "managedState", "docsProtocol"],
+          "properties": {
+            "consumerIntegration": { "const": 1 },
+            "managedState": { "const": 1 },
+            "docsProtocol": { "const": 1 }
+          }
+        },
+        "runtime": {
+          "type": "object", "additionalProperties": false,
+          "required": ["node", "pnpm", "runtimeClosureDigest"],
+          "properties": {
+            "node": { "const": ">=24.18.0 <25" },
+            "pnpm": { "const": ">=11.17.0 <12" },
+            "runtimeClosureDigest": { "$ref": "#/$defs/nonzeroSha256" }
+          }
+        }
+      }
+    },
+    "nonzeroSha256": { "type": "string", "pattern": "^sha256:(?!0{64}$)[0-9a-f]{64}$" },
+    "cohortIds": {
+      "type": "array", "maxItems": 32, "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$" }
+    },
+    "package": {
+      "type": "object", "additionalProperties": false,
+      "required": ["version", "integrity"],
+      "properties": {
+        "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?$" },
+        "integrity": { "type": "string", "pattern": "^sha512-[A-Za-z0-9+/]{86}==$" }
+      }
+    }
+  }
+}

package/schemas/docs-consumer-managed-state/v1.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-consumer-managed-state/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "cohortId", "cohortAuthority", "repository", "packages", "schemas", "runtime", "profilePath", "skillPath", "callerWorkflowPath", "managedStatePath", "assets", "stateDigest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "cohortId": { "type": "string", "minLength": 1 },
+    "cohortAuthority": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["channel", "recordDigest", "qualificationEventDigest", "eligibleAfter", "upgradeFrom", "rollbackTo"],
+      "properties": {
+        "channel": { "enum": ["rc", "stable"] },
+        "recordDigest": { "$ref": "#/$defs/sha256" },
+        "qualificationEventDigest": { "$ref": "#/$defs/sha256" },
+        "eligibleAfter": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$" },
+        "upgradeFrom": { "$ref": "#/$defs/cohortIds" },
+        "rollbackTo": { "$ref": "#/$defs/cohortIds" }
+      }
+    },
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "id", "nameWithOwner"],
+      "properties": {
+        "provider": { "const": "github" },
+        "id": { "type": "string", "pattern": "^[1-9][0-9]*$" },
+        "nameWithOwner": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" }
+      }
+    },
+    "packages": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["docsProtocol", "engineeringFoundation"],
+      "properties": {
+        "docsProtocol": { "$ref": "#/$defs/package" },
+        "engineeringFoundation": { "$ref": "#/$defs/package" }
+      }
+    },
+    "schemas": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["consumerIntegration", "managedState", "docsProtocol"],
+      "properties": {
+        "consumerIntegration": { "const": 1 },
+        "managedState": { "const": 1 },
+        "docsProtocol": { "const": 1 }
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["node", "pnpm", "runtimeClosureDigest"],
+      "properties": {
+        "node": { "const": ">=24.18.0 <25" },
+        "pnpm": { "const": ">=11.17.0 <12" },
+        "runtimeClosureDigest": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "profilePath": { "type": "string", "minLength": 1 },
+    "skillPath": { "type": "string", "minLength": 1 },
+    "callerWorkflowPath": { "type": "string", "minLength": 1 },
+    "managedStatePath": { "type": "string", "minLength": 1 },
+    "assets": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["skillDigest", "callerWorkflowDigest", "assetCatalogDigest", "transitionCatalogDigest", "agentsRouteDigest", "docsScriptsDigest"],
+      "properties": {
+        "skillDigest": { "$ref": "#/$defs/sha256" },
+        "callerWorkflowDigest": { "$ref": "#/$defs/sha256" },
+        "assetCatalogDigest": { "$ref": "#/$defs/sha256" },
+        "transitionCatalogDigest": { "$ref": "#/$defs/sha256" },
+        "agentsRouteDigest": { "$ref": "#/$defs/sha256" },
+        "docsScriptsDigest": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "stateDigest": { "$ref": "#/$defs/sha256" }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "cohortIds": {
+      "type": "array",
+      "maxItems": 32,
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$" }
+    },
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "integrity"],
+      "properties": {
+        "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?$" },
+        "integrity": { "type": "string", "pattern": "^sha512-[A-Za-z0-9+/]{86}==$" }
+      }
+    }
+  }
+}

package/schemas/qualified-docs-cohort/v1.schema.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/qualified-docs-cohort/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "cohortId", "channel", "recordDigest", "qualificationEventDigest", "lifecycleState", "eligibleAfter", "upgradeFrom", "rollbackTo", "canaryRepositoryIds", "packages", "workflow", "assets", "schemas", "runtime"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "cohortId": { "type": "string", "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$" },
+    "channel": { "enum": ["rc", "stable"] },
+    "recordDigest": { "$ref": "#/$defs/nonzeroSha256" },
+    "qualificationEventDigest": { "$ref": "#/$defs/nonzeroSha256" },
+    "lifecycleState": { "enum": ["QUALIFIED", "CANARY", "RECOMMENDED"] },
+    "eligibleAfter": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$" },
+    "upgradeFrom": { "$ref": "#/$defs/cohortIds" },
+    "rollbackTo": { "$ref": "#/$defs/cohortIds" },
+    "canaryRepositoryIds": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 32,
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[1-9][0-9]*$" }
+    },
+    "packages": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["docsProtocol", "engineeringFoundation"],
+      "properties": {
+        "docsProtocol": { "$ref": "#/$defs/package" },
+        "engineeringFoundation": { "$ref": "#/$defs/package" }
+      }
+    },
+    "workflow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repository", "path", "revision", "blobSha"],
+      "properties": {
+        "repository": { "const": "agent-teams-ai/.github" },
+        "path": { "const": ".github/workflows/docs-protocol-check.yml" },
+        "revision": { "$ref": "#/$defs/nonzeroSha" },
+        "blobSha": { "$ref": "#/$defs/nonzeroSha" }
+      }
+    },
+    "assets": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["skillDigest", "callerWorkflowDigest", "assetCatalogDigest", "transitionCatalogDigest"],
+      "properties": {
+        "skillDigest": { "$ref": "#/$defs/sha256" },
+        "callerWorkflowDigest": { "$ref": "#/$defs/sha256" },
+        "assetCatalogDigest": { "$ref": "#/$defs/sha256" },
+        "transitionCatalogDigest": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "schemas": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["consumerIntegration", "managedState", "docsProtocol"],
+      "properties": {
+        "consumerIntegration": { "const": 1 },
+        "managedState": { "const": 1 },
+        "docsProtocol": { "const": 1 }
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["node", "pnpm", "runtimeClosureDigest"],
+      "properties": {
+        "node": { "const": ">=24.18.0 <25" },
+        "pnpm": { "const": ">=11.17.0 <12" },
+        "runtimeClosureDigest": { "$ref": "#/$defs/nonzeroSha256" }
+      }
+    }
+  },
+  "$defs": {
+    "nonzeroSha": { "type": "string", "pattern": "^(?!0{40}$)[0-9a-f]{40}$" },
+    "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "nonzeroSha256": { "type": "string", "pattern": "^sha256:(?!0{64}$)[0-9a-f]{64}$" },
+    "cohortIds": {
+      "type": "array",
+      "maxItems": 32,
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$" }
+    },
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "integrity"],
+      "properties": {
+        "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?$" },
+        "integrity": { "type": "string", "pattern": "^sha512-[A-Za-z0-9+/]{86}==$" }
+      }
+    }
+  }
+}

package/skills/docs/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: docs-authoring
+description: Use when creating, changing, reorganizing, or reviewing governed documentation in this repository.
+---
+
+# Documentation Authoring
+
+Protocol: `agent-teams.docs-protocol/v1`.
+
+## Required workflow
+
+- Read the current types, owners, placement, metadata, and index policy with `pnpm docs:info`.
+- Search first with `pnpm docs:find -- --text query`.
+- Reuse or relate existing authority instead of creating a competing source.
+- Preview with `pnpm docs:new -- --type TYPE --id ID --title TITLE --owner OWNER --summary SUMMARY --dry-run`.
+- Review the exact destination, metadata, relations, anchors, and diagnostics.
+- Apply with `pnpm docs:new -- --type TYPE --id ID --title TITLE --owner OWNER --summary SUMMARY --apply` after review.
+- Manually update the reported index/link exactly when reachability requires it.
+- Finish with `pnpm docs:check` after the index is current.
+
+## Rules
+
+- Never invent owners, types, statuses, paths, or metadata outside `docs:info`.
+- If dependencies are absent, use only `pnpm install --frozen-lockfile`; never use npx, dlx, or latest tags.
+- Keep preview and apply inputs identical.
+- Stop when recovery is required; use `pnpm docs:doctor` before `pnpm docs:recover`.
+- Resolve required anchors and blockers before apply.
+- Do not bypass repository scripts or hand-edit transaction evidence.