@agentproto/corpus-cli 0.1.0-alpha.1 → 0.1.0-alpha.2

package/dist/specs/resources/aip-21/draft/AGENCY.schema.json

@@ -0,0 +1,454 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentproto.sh/schemas/aip-21/AGENCY.schema.json",
+  "title": "agentagencies/v2 frontmatter (AIP-21)",
+  "description": "Validates the YAML frontmatter portion of an AIP-21 AGENCY.md (workspace root or per-context view). The single doctype 'agency.workspace/v2' is used in both modes; the host distinguishes by checking whether `extends` is set. Per-doctype schemas (service, engagement, agreement, deliverable, invoice, counterparty, procedure, pricing-model, routine, capacity) are delegated to AIP-18 (COLLECTION.md / ITEM.md).",
+  "type": "object",
+  "required": ["schema", "name", "title", "description", "version"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "const": "agency.workspace/v2",
+      "description": "Discriminator for the AIP-21 workspace doctype."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 96,
+      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+      "description": "Stable kebab-case identifier for the agency or view."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "description": "Human-readable agency title."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000,
+      "description": "One-paragraph statement of purpose: what this agency does and who it serves."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[A-Za-z0-9.-]+)?$",
+      "description": "Semantic version of the WORKSPACE shape. Bump on collection / scope / lifecycle / lint / defaults changes. Independent of the agency's content version."
+    },
+    "extends": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^(\\.\\./|\\./)[^\\s]+/AGENCY\\.md$",
+      "description": "OPTIONAL — relative path to a parent AGENCY.md. Presence makes the manifest a VIEW; absence makes it a WORKSPACE ROOT. Recursive composition; maximum chain depth is 8."
+    },
+    "appliesTo": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^(ws://(operators|companies|skills)/[a-z][a-z0-9-]*|\\.\\./[^\\s]+)$",
+        "description": "Either a ws:// ref to an AIP-9 operator / AIP-6 company / AIP-3 skill, or a relative path to a consumer workspace folder."
+      },
+      "uniqueItems": true,
+      "description": "OPTIONAL — list of consumers this VIEW adapts the agency for. Hosts MUST refuse the view if any binding does not resolve. Not inherited; views declare their own scope."
+    },
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "legalEntity": {
+          "type": "string",
+          "pattern": "^ws://companies/[a-z][a-z0-9-]*$",
+          "description": "OPTIONAL — AIP-6 ref to the company that legally signs agreements and issues invoices. When set, hosts SHOULD resolve this ref to populate legalName and taxId from the AIP-6 record."
+        },
+        "legalName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "OPTIONAL — display string for the legal entity name. Used when legalEntity is absent or to override the AIP-6 record's legalName."
+        },
+        "taxId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "OPTIONAL — tax identifier (VAT, EIN, GST, etc.). Hosts MUST treat this string as opaque; format validation belongs to per-jurisdiction tooling."
+        },
+        "jurisdiction": {
+          "type": "string",
+          "pattern": "^[A-Z]{2}$",
+          "description": "OPTIONAL — primary jurisdiction the agency operates under, as ISO 3166-1 alpha-2 (e.g. FR, US, GB, DE)."
+        },
+        "defaultCurrency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$",
+          "description": "OPTIONAL — default currency for new invoices, as ISO 4217 (e.g. EUR, USD, GBP). Per-engagement overrides take precedence."
+        }
+      },
+      "description": "Commercial-flavored identity block. All fields optional; agencies operating as a sole operator with no counterparty billing may omit the block entirely."
+    },
+    "executor": {
+      "type": "string",
+      "pattern": "^ws://operators/[a-z][a-z0-9-]*$",
+      "description": "OPTIONAL — AIP-9 default executor operator. The host activates this operator when an item with no explicit assignee surfaces."
+    },
+    "governance": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "description": "OPTIONAL — AIP-7 policy or audit binding. May be a path to an AIP-7 policy file or a ws:// ref. Status-transition approvals, signature gates on agreements, and audit log routing flow through this ref. Agreements MUST be signed; the default policy lives here."
+    },
+    "knowledge": {
+      "type": "string",
+      "pattern": "^ws://wikis/[a-z][a-z0-9-]*(/KNOWLEDGE\\.md)?$",
+      "description": "OPTIONAL — AIP-10 KNOWLEDGE.md ref. Wiki this agency refers to (case studies, prior-art, methodology)."
+    },
+    "work": {
+      "type": "string",
+      "pattern": "^ws://workspaces/[a-z][a-z0-9-]*(/WORK\\.md)?$",
+      "description": "OPTIONAL — AIP-20 work workspace binding. Items in `deliverable` MAY be tracked as work items in the bound workspace."
+    },
+    "playbook": {
+      "type": "string",
+      "pattern": "^ws://playbooks/[a-z][a-z0-9-]*$",
+      "description": "OPTIONAL — AIP-12 active playbook. Governs the routine plays this agency runs."
+    },
+    "companies": {
+      "type": "string",
+      "pattern": "^ws://companies(/[a-z][a-z0-9-]*)?$",
+      "description": "OPTIONAL — AIP-6 companies root. Resolution root for `counterparty` items: a counterparty's companyRef resolves under this binding."
+    },
+    "collections": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/collectionEntry"
+      },
+      "default": [],
+      "description": "Collections enabled by this agency. Three forms supported: inline (full COLLECTION.md frontmatter), file ref, or registry import. Merge-by-effective-name (alias if set, otherwise the collection's name) across the extends chain."
+    },
+    "lifecycle": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether cross-collection lifecycle propagation is active. When false, no lifecycle rules fire — items keep their stored statuses regardless of related items."
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "when", "forCollection", "bubbleStatus"],
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*$",
+                "description": "Stable kebab-case rule id. Merge key when composing across extends."
+              },
+              "when": {
+                "type": "string",
+                "pattern": "^(all-items-in-collection-terminal|any-linked-item-status|linked-item-terminal|no-linked-items|custom:[a-z][a-z0-9-]*)$",
+                "description": "Predicate id from the recognised vocabulary. Custom predicates are host-defined keyed by `id`."
+              },
+              "forCollection": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+                "description": "Effective name of the collection whose items receive the bubbled status. MUST appear in the workspace's merged collections array."
+              },
+              "bubbleStatus": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*$",
+                "description": "Status id to set on the target item when the predicate holds. MUST exist on the forCollection's state machine."
+              },
+              "params": {
+                "type": "object",
+                "additionalProperties": true,
+                "default": {},
+                "description": "Predicate parameters. Common keys: sourceCollection (collection whose items the predicate inspects), linkField (field on source items pointing at the target), terminalStatuses (subset of terminal statuses to count), statusEquals (specific status to match)."
+              }
+            }
+          },
+          "default": [],
+          "description": "Cross-collection lifecycle rules. Merge-by-id vs parent. Hosts MUST detect graph cycles in the (forCollection, sourceCollection) edge set and refuse with agency_lifecycle_cycle (HARD)."
+        }
+      },
+      "description": "Engagement lifecycle helpers — workspace-level rules for cross-collection state propagation. The AIP-21 distinctive contribution."
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "containment": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Whether the containment axis is active. ONE-WAY SWITCH: once true at any ancestor, descendants MUST NOT set false (would orphan items). Refusal: agency_scope_disable (HARD)."
+            },
+            "field": {
+              "type": "string",
+              "pattern": "^[a-z][a-zA-Z0-9_]*$",
+              "default": "parent",
+              "description": "Item field name carrying the containment ref."
+            },
+            "rules": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "allowedKinds": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+                  },
+                  "uniqueItems": true,
+                  "description": "OPTIONAL — collection names allowed as containment parents."
+                },
+                "maxDepth": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 32,
+                  "description": "OPTIONAL — maximum containment depth."
+                }
+              },
+              "description": "OPTIONAL containment constraints."
+            }
+          },
+          "description": "Containment axis (parent/child)."
+        },
+        "applicability": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "Whether the applicability axis is active."
+            },
+            "field": {
+              "type": "string",
+              "pattern": "^[a-z][a-zA-Z0-9_]*$",
+              "default": "appliesTo",
+              "description": "Item field name carrying the applicability ref list."
+            },
+            "valueClass": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9-]*$",
+              "description": "Class of refs the field accepts. Recognised classes: client, market, service, company, role, role-and-company, operator. ONE-WAY SWITCH: once set at any ancestor, descendants MUST NOT change. Refusal: agency_scope_value_class_drift (HARD)."
+            }
+          },
+          "description": "Applicability axis (who the item is about / scoped to)."
+        },
+        "ownership": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Whether the ownership axis is active."
+            },
+            "field": {
+              "type": "string",
+              "pattern": "^[a-z][a-zA-Z0-9_]*$",
+              "default": "owner",
+              "description": "Workspace-level default item field name carrying the ownership ref."
+            },
+            "policy": {
+              "enum": ["strict", "inherit", "open"],
+              "default": "inherit",
+              "description": "Workspace-level ownership policy. 'strict' requires every collection's ownership.required to be true; 'inherit' delegates; 'open' permits any collection to omit ownership."
+            }
+          },
+          "description": "Ownership axis (who is doing the item)."
+        }
+      },
+      "description": "Workspace-level scope axes — three orthogonal axes (containment / applicability / ownership) declared once per agency."
+    },
+    "lints": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "severity"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$",
+            "description": "Stable kebab-case lint id. Merge key when composing with extends parent."
+          },
+          "kind": {
+            "enum": [
+              "stale-engagement",
+              "unsigned-agreement",
+              "overdue-invoice",
+              "broken-procedure-ref",
+              "orphan-across-collections",
+              "stale-tree",
+              "broken-parent-ref",
+              "scope-mismatch",
+              "custom"
+            ],
+            "description": "Workspace-spanning lint algorithm. AIP-18 per-collection lints (missing-owner, overdue, required-field, etc.) live on COLLECTION.md and are NOT redeclared here. 'custom' delegates to a host-defined check identified by `id`."
+          },
+          "severity": {
+            "enum": ["error", "warn", "info"],
+            "description": "Lint severity. Children may soften; governance policies MAY forbid softening below `error`."
+          },
+          "params": {
+            "type": "object",
+            "additionalProperties": true,
+            "default": {},
+            "description": "Kind-specific parameters."
+          }
+        }
+      },
+      "default": [],
+      "description": "Workspace-spanning lints. Merge-by-id vs parent."
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "workflow": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "description": "OPTIONAL — default AIP-15 WORKFLOW.md path or ref."
+        },
+        "approvalClass": {
+          "type": "string",
+          "pattern": "^(auto|always|on-mutate|policy:[A-Za-z0-9_./:-]+)$",
+          "description": "Approval class for mutations. 'auto' = no gate; 'always' = every mutation requires approval; 'on-mutate' = approval on field-level mutations; 'policy:<ref>' = delegate to an AIP-7 policy."
+        },
+        "auditMutations": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether mutations are audited. ONE-WAY SWITCH: once true at any ancestor, descendants MUST NOT set false. Refusal: agency_audit_downgrade (HARD)."
+        }
+      },
+      "description": "Routine workflow defaults. Composes with AIP-15."
+    },
+    "engagement": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "terms": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "contractRequired": {
+              "type": "boolean",
+              "default": false,
+              "description": "Whether engagement items require a corresponding agreement item. ONE-WAY SWITCH: once true at any ancestor, descendants MUST NOT set false (commercial protection against engagements without paperwork). Refusal: agency_contract_required_downgrade (HARD)."
+            },
+            "defaultPaymentTerms": {
+              "type": "string",
+              "pattern": "^(net-[0-9]+|due-on-receipt|prepaid|[a-z][a-z0-9-]*)$",
+              "description": "OPTIONAL — default payment terms for new invoices. Common values: net-15, net-30, net-60, due-on-receipt, prepaid. Custom kebab-case strings permitted."
+            },
+            "defaultCurrency": {
+              "type": "string",
+              "pattern": "^[A-Z]{3}$",
+              "description": "OPTIONAL — default currency for engagement-derived invoices, as ISO 4217. Falls back to identity.defaultCurrency if unset."
+            }
+          },
+          "description": "Default commercial terms applied to new engagement and invoice items."
+        }
+      },
+      "description": "Engagement-specific terms (AIP-21 distinctive)."
+    },
+    "display": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "homePage": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9_:-]*$",
+          "description": "OPTIONAL — id of the item to use as the agency landing page."
+        },
+        "defaultGrouping": {
+          "enum": ["kind", "status", "counterparty", "engagement"],
+          "description": "Default grouping for list views."
+        },
+        "defaultView": {
+          "enum": ["list", "board", "timeline", "dashboard"],
+          "description": "Default rendering mode."
+        }
+      },
+      "description": "Display hints for UIs that render the agency. Runtime-agnostic."
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": {},
+      "description": "Vendor-specific extensions, namespaced under <vendor>. Deep-merged across the extends chain. MUST NOT change the meaning of any spec field."
+    }
+  },
+  "allOf": [
+    {
+      "description": "A view (any manifest with appliesTo set) MUST extend a parent. A workspace-root manifest has neither field.",
+      "if": {
+        "required": ["appliesTo"],
+        "properties": {
+          "appliesTo": { "type": "array", "minItems": 1 }
+        }
+      },
+      "then": {
+        "required": ["extends"]
+      }
+    }
+  ],
+  "$defs": {
+    "collectionEntry": {
+      "oneOf": [
+        { "$ref": "#/$defs/collectionInline" },
+        { "$ref": "#/$defs/collectionRef" }
+      ],
+      "description": "One collection declaration. Either an inline AIP-18 collection schema, or a ref (path or ws:// URI) optionally aliased and version-pinned."
+    },
+    "collectionInline": {
+      "type": "object",
+      "required": ["inline"],
+      "additionalProperties": false,
+      "properties": {
+        "inline": {
+          "$ref": "https://agentproto.sh/schemas/aip-18/COLLECTION.schema.json#/$defs/schema",
+          "description": "Full AIP-18 collection.schema/v1 frontmatter, parsed in-place. The host registers the collection directly via AIP-18's defineCollection without loading a separate file."
+        }
+      },
+      "description": "Inline collection declaration. Full AIP-18 schema embedded; hosts MUST validate it against the AIP-18 COLLECTION schema before registration."
+    },
+    "collectionRef": {
+      "type": "object",
+      "required": ["ref"],
+      "additionalProperties": false,
+      "properties": {
+        "ref": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "pattern": "^((\\.\\./|\\./)[^\\s]+/COLLECTION\\.md|ws://collections/[a-z][a-z0-9-]*)$",
+          "description": "Either a relative path to a COLLECTION.md (file ref) or a ws://collections/<slug> URI (registry import)."
+        },
+        "alias": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+          "minLength": 2,
+          "maxLength": 96,
+          "description": "OPTIONAL — workspace-local name to expose the collection under. Items in this workspace reference the alias, not the upstream name. Two collections resolving to the same effective name is a HARD failure: agency_collection_alias_conflict."
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "OPTIONAL — semver range (e.g. \"1.x\", \"^1.2\", \"1.2.0\"). When set, schema bumps outside the range fail with collection_item_schema_pinned_drift (HARD) at item load time."
+        }
+      },
+      "description": "Collection ref declaration. Either a file path or a registry URI."
+    }
+  }
+}