@agent-teams/docs-protocol-agent-teams 0.0.0 → 0.1.0

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

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-consumer-integration-profile/v3",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "repository",
+    "integrationRoot",
+    "packageManager",
+    "profilePath",
+    "skillPath",
+    "callerWorkflowPath",
+    "managedStatePath",
+    "cohort",
+    "qualification"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 3 },
+    "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"
+    },
+    "qualification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["contractPath", "gateCommand"],
+      "properties": {
+        "contractPath": {
+          "const": "architecture/foundation/docs-protocol-qualification.json"
+        },
+        "gateCommand": { "const": "pnpm docs:protocol:check" }
+      }
+    },
+    "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": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/cohortBinding"
+    }
+  }
+}

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

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-consumer-managed-state/v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "cohortId",
+    "cohortAuthority",
+    "repository",
+    "packages",
+    "schemas",
+    "runtime",
+    "profilePath",
+    "skillPath",
+    "callerWorkflowPath",
+    "managedStatePath",
+    "assets",
+    "stateDigest"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "cohortId": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$"
+    },
+    "cohortAuthority": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "channel",
+        "recordDigest",
+        "qualificationEventDigest",
+        "eligibleAfter",
+        "upgradeFrom",
+        "rollbackTo"
+      ],
+      "properties": {
+        "channel": { "enum": ["rc", "stable"] },
+        "recordDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        },
+        "qualificationEventDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$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": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/cohortIds"
+        },
+        "rollbackTo": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$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": {
+      "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/cohortCore/properties/packages"
+    },
+    "schemas": {
+      "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/cohortCore/properties/schemas"
+    },
+    "runtime": {
+      "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/cohortCore/properties/runtime"
+    },
+    "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": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        },
+        "callerWorkflowDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        },
+        "assetCatalogDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        },
+        "transitionCatalogDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        },
+        "agentsRouteDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        },
+        "docsScriptsDigest": {
+          "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+        }
+      }
+    },
+    "stateDigest": {
+      "$ref": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2#/$defs/nonzeroSha256"
+    }
+  }
+}

package/schemas/docs-protocol-qualification-receipt/v3.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-protocol-qualification-receipt/v3",
+  "title": "Docs Protocol Cohort v2 admission receipt",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "receiptDigest",
+    "cohortAdmissible",
+    "profileSchemaVersion",
+    "cohort",
+    "packages",
+    "schemas",
+    "runtime",
+    "checks"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 3 },
+    "receiptDigest": { "$ref": "#/$defs/digest" },
+    "cohortAdmissible": { "const": true },
+    "profileSchemaVersion": { "const": 3 },
+    "cohort": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "cohortId", "recordDigest", "qualificationEventDigest"],
+      "properties": {
+        "schemaVersion": { "const": 2 },
+        "cohortId": { "type": "string", "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$" },
+        "recordDigest": { "$ref": "#/$defs/digest" },
+        "qualificationEventDigest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "packages": {
+      "type": "array",
+      "minItems": 5,
+      "maxItems": 5,
+      "prefixItems": [
+        { "$ref": "#/$defs/repositoryMutation" },
+        { "$ref": "#/$defs/documentAuthoring" },
+        { "$ref": "#/$defs/docsProtocol" },
+        { "$ref": "#/$defs/docsProtocolAgentTeams" },
+        { "$ref": "#/$defs/engineeringFoundation" }
+      ],
+      "items": false
+    },
+    "schemas": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["consumerIntegration", "managedState", "docsProtocol"],
+      "properties": {
+        "consumerIntegration": { "const": 3 },
+        "managedState": { "const": 2 },
+        "docsProtocol": { "const": 1 }
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runtimeClosureDigest"],
+      "properties": { "runtimeClosureDigest": { "$ref": "#/$defs/digest" } }
+    },
+    "checks": {
+      "type": "array",
+      "minItems": 7,
+      "maxItems": 7,
+      "prefixItems": [
+        { "const": "profile-v3" },
+        { "const": "cohort-v2" },
+        { "const": "five-package-closure" },
+        { "const": "exact-package-versions" },
+        { "const": "exact-package-integrities" },
+        { "const": "schema-bindings-3-2-1" },
+        { "const": "runtime-closure-digest" }
+      ],
+      "items": false
+    }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:(?!0{64}$)[0-9a-f]{64}$" },
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["key", "name", "version", "integrity"],
+      "properties": {
+        "key": { "type": "string" },
+        "name": { "type": "string" },
+        "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?$" },
+        "integrity": { "type": "string", "pattern": "^sha512-[A-Za-z0-9+/]{86}==$" }
+      }
+    },
+    "repositoryMutation": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/package" }],
+      "properties": { "key": { "const": "repositoryMutation" }, "name": { "const": "@agent-teams/repository-mutation" } }
+    },
+    "documentAuthoring": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/package" }],
+      "properties": { "key": { "const": "documentAuthoring" }, "name": { "const": "@agent-teams/document-authoring" } }
+    },
+    "docsProtocol": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/package" }],
+      "properties": { "key": { "const": "docsProtocol" }, "name": { "const": "@agent-teams/docs-protocol" } }
+    },
+    "docsProtocolAgentTeams": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/package" }],
+      "properties": { "key": { "const": "docsProtocolAgentTeams" }, "name": { "const": "@agent-teams/docs-protocol-agent-teams" } }
+    },
+    "engineeringFoundation": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/package" }],
+      "properties": { "key": { "const": "engineeringFoundation" }, "name": { "const": "@agent-teams/engineering-foundation" } }
+    }
+  }
+}

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

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/qualified-docs-cohort/v2",
+  "type": "object",
+  "allOf": [
+    { "$ref": "#/$defs/cohortCore" },
+    {
+      "type": "object",
+      "required": ["lifecycleState", "canaryRepositoryIds"],
+      "properties": {
+        "lifecycleState": { "enum": ["QUALIFIED", "CANARY", "RECOMMENDED"] },
+        "canaryRepositoryIds": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[1-9][0-9]*$" }
+        }
+      }
+    }
+  ],
+  "unevaluatedProperties": false,
+  "$defs": {
+    "cohortBinding": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/cohortCore" }],
+      "unevaluatedProperties": false
+    },
+    "cohortCore": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "cohortId",
+        "channel",
+        "recordDigest",
+        "qualificationEventDigest",
+        "eligibleAfter",
+        "upgradeFrom",
+        "rollbackTo",
+        "packages",
+        "workflow",
+        "assets",
+        "schemas",
+        "runtime"
+      ],
+      "properties": {
+        "schemaVersion": { "const": 2 },
+        "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": [
+            "repositoryMutation",
+            "documentAuthoring",
+            "docsProtocol",
+            "docsProtocolAgentTeams",
+            "engineeringFoundation"
+          ],
+          "properties": {
+            "repositoryMutation": { "$ref": "#/$defs/package" },
+            "documentAuthoring": { "$ref": "#/$defs/package" },
+            "docsProtocol": { "$ref": "#/$defs/package" },
+            "docsProtocolAgentTeams": { "$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/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": 3 },
+            "managedState": { "const": 2 },
+            "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" }
+          }
+        }
+      }
+    },
+    "nonzeroSha": { "type": "string", "pattern": "^(?!0{40}$)[0-9a-f]{40}$" },
+    "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

@@ -10,20 +10,22 @@ 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`.
+- Search first (docs-protocol find) 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`.
+- Preview (docs-protocol new) 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.
+- Apply (docs-protocol new) with `pnpm docs:new -- --type TYPE --id ID --title TITLE --owner OWNER --summary SUMMARY --apply` after review.
+- If reachability is `manual-required`, update the reported index/link by adding the exact `markdownLink` to the reported `indexPath`.
+- Refresh bounded context with `pnpm exec docs-protocol context --consumer "CONSUMER" --profile "PROFILE" --max-documents 8 --max-bytes 32768`; copy CONSUMER and PROFILE from the existing `docs:info` script, never guess a default profile.
 - For edits, preserve canonical frontmatter and sidecar ownership; use the repository's governed review flow rather than bypassing the create-only writer.
 - For accepted authority, record supersession explicitly instead of silently rewriting history.
-- Finish with the full consumer gate `pnpm docs:protocol:check` after the index is current.
+- Run `pnpm docs:check` (docs-protocol check), then the full consumer gate `pnpm docs:protocol: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.
+- Use repository scripts except the explicit installed read-only context command above; never hand-edit transaction evidence.