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

package/dist/specs/resources/aip-13/draft/WORK_ITEM.schema.json

@@ -0,0 +1,547 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentproto.sh/schemas/aip-13/WORK_ITEM.schema.json",
+  "title": "agentwork/v1 frontmatter (AIP-13)",
+  "description": "Validates the YAML frontmatter portion of an AIP-13 doctype. The `schema` discriminator selects between the work-item branch (project / initiative / task — the original `work/v1` doctype, with the `kind` field discriminating the three variants) and the workspace branch (`work.workspace/v1` — used both as the workspace-root manifest at the company root and as a per-consumer view that extends a parent manifest).",
+  "oneOf": [{ "$ref": "#/$defs/workItem" }, { "$ref": "#/$defs/workspace" }],
+  "$defs": {
+    "workItem": {
+      "type": "object",
+      "required": ["schema", "slug", "kind", "title", "status", "scope"],
+      "properties": {
+        "schema": {
+          "const": "work/v1",
+          "description": "Spec discriminator. Always 'work/v1' for the project / initiative / task doctypes."
+        },
+        "slug": {
+          "type": "string",
+          "minLength": 2,
+          "maxLength": 64,
+          "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+          "description": "Machine identifier. Lowercase, digits, dashes. Unique within (company, kind)."
+        },
+        "kind": {
+          "enum": ["project", "initiative", "task"],
+          "description": "The doctype variant. Drives per-kind constraints."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Human-readable display title."
+        },
+        "status": {
+          "enum": [
+            "open",
+            "claimed",
+            "in-progress",
+            "blocked",
+            "done",
+            "archived"
+          ],
+          "description": "Current status. Transitions enforced by the host."
+        },
+        "parent": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["kind", "ref"],
+              "additionalProperties": false,
+              "properties": {
+                "kind": { "enum": ["project", "initiative"] },
+                "ref": {
+                  "type": "string",
+                  "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+                }
+              }
+            }
+          ],
+          "description": "Containment axis — what this is part of. Cascade-delete semantics. Null for top-level."
+        },
+        "scope": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "company": {
+              "type": ["string", "null"],
+              "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+            },
+            "role": {
+              "type": ["string", "null"],
+              "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+            },
+            "operator": {
+              "type": ["string", "null"],
+              "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+            },
+            "project": {
+              "type": ["string", "null"],
+              "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+            }
+          },
+          "description": "Applicability axis — most-restrictive non-empty field wins; AND across fields. Inherits from parent when empty."
+        },
+        "assignee": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["kind", "ref"],
+              "additionalProperties": false,
+              "properties": {
+                "kind": { "enum": ["operator", "user"] },
+                "ref": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }
+              }
+            }
+          ],
+          "description": "Ownership axis — tasks only. Null = unclaimed."
+        },
+        "lead": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["kind", "ref"],
+              "additionalProperties": false,
+              "properties": {
+                "kind": { "enum": ["operator", "user"] },
+                "ref": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }
+              }
+            }
+          ],
+          "description": "Ownership axis — projects and initiatives only. Null = unassigned."
+        },
+        "members": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["kind", "ref"],
+            "additionalProperties": false,
+            "properties": {
+              "kind": { "enum": ["operator", "user", "role"] },
+              "ref": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }
+            }
+          },
+          "default": [],
+          "description": "Projects only — explicit member list when access is narrower than role-based."
+        },
+        "attachments": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "artifacts": { "type": "array", "items": { "type": "string" } },
+            "wiki": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+              }
+            },
+            "lessons": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+              }
+            },
+            "conversations": { "type": "array", "items": { "type": "string" } },
+            "deliverables": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+              }
+            },
+            "objectives": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+              }
+            }
+          },
+          "description": "Inert references — informational only. NOT containment. Removing target MUST NOT cascade."
+        },
+        "governance": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "approval_required": { "type": "boolean", "default": false },
+            "signers": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["kind", "ref"],
+                "additionalProperties": false,
+                "properties": {
+                  "kind": { "enum": ["operator", "user", "role"] },
+                  "ref": { "type": "string" }
+                }
+              },
+              "default": []
+            }
+          },
+          "description": "AIP-7 governance hooks."
+        },
+        "deadline": {
+          "type": ["string", "null"],
+          "format": "date-time",
+          "description": "Optional ISO 8601 deadline."
+        },
+        "priority": {
+          "enum": ["low", "normal", "high"],
+          "default": "normal"
+        },
+        "labels": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "default": []
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": true,
+          "default": {},
+          "description": "Vendor extensions under metadata.<vendor>.<field>."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "kind": { "const": "task" } },
+            "required": ["kind"]
+          },
+          "then": {
+            "not": { "required": ["lead"] },
+            "description": "Tasks MUST NOT use 'lead' — they have an 'assignee'."
+          }
+        },
+        {
+          "if": {
+            "properties": { "kind": { "const": "project" } },
+            "required": ["kind"]
+          },
+          "then": {
+            "not": { "required": ["assignee"] },
+            "description": "Projects MUST NOT use 'assignee' — they have a 'lead'."
+          }
+        },
+        {
+          "if": {
+            "properties": { "kind": { "const": "initiative" } },
+            "required": ["kind"]
+          },
+          "then": {
+            "not": { "required": ["assignee"] },
+            "description": "Initiatives MUST NOT use 'assignee' — they have a 'lead'."
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "kind": { "not": { "const": "project" } }
+            },
+            "required": ["kind"]
+          },
+          "then": {
+            "not": { "required": ["members"] },
+            "description": "Only projects MAY declare 'members'."
+          }
+        },
+        {
+          "if": {
+            "anyOf": [
+              { "not": { "required": ["parent"] } },
+              { "properties": { "parent": { "const": null } } }
+            ]
+          },
+          "then": {
+            "properties": {
+              "scope": { "required": ["company"] }
+            },
+            "description": "Top-level doctypes (no parent) MUST set scope.company."
+          }
+        }
+      ]
+    },
+    "workspace": {
+      "type": "object",
+      "required": ["schema", "name", "title", "description", "version"],
+      "additionalProperties": false,
+      "description": "Workspace manifest doctype. Used both as the root manifest of a work tree (no `extends`) and as a per-consumer view (with `extends`). The same schema validates both modes; the host distinguishes by whether `extends` is set. Mirrors the AIP-10 `knowledge.workspace/v1` shape so the registry-of-views pattern is uniform across the AIP family.",
+      "properties": {
+        "schema": {
+          "const": "work.workspace/v1",
+          "description": "Discriminator for the workspace manifest doctype."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 2,
+          "maxLength": 96,
+          "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+          "description": "Stable kebab-case identifier for the workspace or view."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Human-readable workspace title."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2000,
+          "description": "One-paragraph statement of purpose: what this workspace (or view) is for and who uses it."
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[A-Za-z0-9.-]+)?$",
+          "description": "Semantic version of the WORKSPACE shape. Bump on itemKinds / statuses / lints / scope-default changes. Independent of the work tree's content version."
+        },
+        "extends": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "pattern": "^(\\.\\./|\\./)[^\\s]+/WORK\\.md$",
+          "description": "OPTIONAL — relative path to a parent WORK.md. Presence makes the manifest a VIEW; absence makes it a WORKSPACE ROOT. Recursive composition: parents may themselves declare `extends`. 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 workspace for. Hosts MUST refuse the view if any binding does not resolve. Not inherited; views declare their own scope."
+        },
+        "executor": {
+          "type": "string",
+          "pattern": "^ws://operators/[a-z][a-z0-9-]*$",
+          "description": "OPTIONAL — AIP-9 operator that runs work items emitted by this workspace (e.g. picks up `claimed` tasks, drives `in-progress`). The host activates this operator for the workspace's automation passes."
+        },
+        "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. Approval gates on status transitions and assignment changes flow through this ref."
+        },
+        "knowledge": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "description": "OPTIONAL — AIP-10 wiki this workspace refers to. Typically a `ws://wikis/<slug>/KNOWLEDGE.md` ref or a relative path to a KNOWLEDGE.md. Lets work items resolve `attachments.wiki[]` against the bound wiki by default."
+        },
+        "itemKinds": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "additionalProperties": false,
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*$",
+                "description": "Kind name. Matches the `kind` field on a work-item doctype. Merge key when composing with extends parent."
+              },
+              "enabled": {
+                "type": "boolean",
+                "default": true,
+                "description": "Whether this kind is allowed in the workspace. Child views can disable a parent's kind by setting `enabled: false`."
+              },
+              "fields": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[a-z][A-Za-z0-9_]*$"
+                },
+                "default": [],
+                "description": "Canonical fields beyond the base spec. Child views append fields to parent's set."
+              },
+              "icon": {
+                "type": "string",
+                "maxLength": 8,
+                "description": "OPTIONAL — display hint, typically a single emoji."
+              },
+              "description": {
+                "type": "string",
+                "maxLength": 1000,
+                "description": "OPTIONAL — prose describing what items of this kind capture."
+              }
+            }
+          },
+          "default": [],
+          "description": "Work-item kinds this workspace tracks. Merge-by-name against the extends parent: a child entry with the same name replaces the parent's; new names are appended. Custom kinds (beyond project / initiative / task) are allowed when an adapter understands them."
+        },
+        "statuses": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "label"],
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*$",
+                "description": "Stable kebab-case status id. Merge key when composing with extends parent."
+              },
+              "label": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 64,
+                "description": "Human-readable status label."
+              },
+              "terminal": {
+                "type": "boolean",
+                "default": false,
+                "description": "Whether this status is terminal (e.g. done, cancelled). Terminal states accept no further transitions except to `archived`-equivalents."
+              },
+              "transitionsTo": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[a-z][a-z0-9-]*$"
+                },
+                "uniqueItems": true,
+                "default": [],
+                "description": "Allowed next status ids. The host MUST refuse transitions outside this list."
+              }
+            }
+          },
+          "default": [],
+          "description": "Status state machine. Merge-by-id against the extends parent: a child entry with the same id replaces the parent's; new ids are appended. A child that flips a parent status's `terminal` classification SHOULD trigger a `work_status_drift` warning."
+        },
+        "scope": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "defaultContainment": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+              "description": "OPTIONAL — slug of a default parent project/initiative new items default to."
+            },
+            "defaultApplicability": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+              },
+              "uniqueItems": true,
+              "default": [],
+              "description": "OPTIONAL — default applicability axis values (role / operator / project slugs) for new items in this view."
+            },
+            "defaultOwner": {
+              "type": "string",
+              "pattern": "^ws://operators/[a-z][a-z0-9-]*$",
+              "description": "OPTIONAL — AIP-9 operator slug used as default `assignee` (tasks) or `lead` (projects/initiatives) when new items are created without explicit ownership."
+            },
+            "ownershipPolicy": {
+              "enum": ["strict", "inherit", "open"],
+              "default": "inherit",
+              "description": "How ownership is enforced. 'strict' = ownership MUST match scope.applicability; 'inherit' = empty ownership inherits from containment chain; 'open' = any operator may claim regardless of scope."
+            }
+          },
+          "description": "Defaults for the three orthogonal scope axes (containment / applicability / ownership). Each leaf field overrides independently across the extends chain."
+        },
+        "lints": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "kind", "appliesTo", "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": [
+                  "missing-owner",
+                  "overdue",
+                  "orphan",
+                  "broken-ref",
+                  "stale",
+                  "scope-widening",
+                  "custom"
+                ],
+                "description": "Lint algorithm. 'custom' delegates to a host-defined check identified by `id`."
+              },
+              "appliesTo": {
+                "type": "string",
+                "pattern": "^([a-z][a-z0-9-]*|\\*)$",
+                "description": "Item kind name (e.g. 'task') or '*' for all kinds."
+              },
+              "severity": {
+                "enum": ["error", "warn", "info"],
+                "description": "Lint severity. Child views may soften (warn -> info) but governance policies may forbid that."
+              },
+              "params": {
+                "type": "object",
+                "additionalProperties": true,
+                "default": {},
+                "description": "Kind-specific parameters. e.g. { days: 14 } for 'overdue'; { days: 30 } for 'stale'."
+              }
+            }
+          },
+          "default": [],
+          "description": "Lint rules. Merge-by-id against the extends parent: a child entry with the same id replaces the parent's; new ids are appended."
+        },
+        "defaults": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "workflow": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "description": "OPTIONAL — default AIP-15 WORKFLOW.md path or ref. Items without an explicit workflow inherit this one."
+            },
+            "approvalClass": {
+              "type": "string",
+              "pattern": "^(auto|always|on-mutate|policy:[^\\s]+)$",
+              "description": "OPTIONAL — default AIP-7 approval class for status transitions and ownership changes. 'auto' = no approval; 'always' = approval on every change; 'on-mutate' = only on field mutation; 'policy:<ref>' = delegate to a named policy."
+            }
+          },
+          "description": "Default workflow / approval bindings. Each leaf field overrides independently across the extends chain."
+        },
+        "display": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "homePage": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+              "description": "OPTIONAL — slug of the work item to use as the workspace landing page."
+            },
+            "defaultGrouping": {
+              "enum": ["kind", "status", "owner"],
+              "description": "Default grouping for list / board UIs."
+            }
+          },
+          "description": "Display hints for UIs that render the workspace. Runtime-agnostic."
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": true,
+          "default": {},
+          "description": "Vendor-specific extensions, namespaced under <vendor>. Deep-merged across the extends chain."
+        }
+      },
+      "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"]
+          }
+        }
+      ]
+    }
+  }
+}