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

package/dist/specs/resources/aip-11/draft/LESSON.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentproto.sh/schemas/aip-11/LESSON.schema.json",
+  "title": "LESSON.md frontmatter (AIP-11)",
+  "description": "Validates the YAML frontmatter portion of an AIP-11 LESSON.md file — one transferable lesson distilled from a completed run.",
+  "type": "object",
+  "required": ["schema", "slug", "title", "trigger", "outcome", "evidence"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "const": "learning/v1",
+      "description": "Spec identifier. Must be the literal string 'learning/v1'."
+    },
+    "slug": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 80,
+      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+      "description": "Machine identifier, also the filename. Lowercase, digits, dashes. Imperative voice recommended."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "description": "One-sentence imperative title — what to do or avoid."
+    },
+    "trigger": {
+      "type": "object",
+      "required": ["description"],
+      "additionalProperties": false,
+      "properties": {
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1000,
+          "description": "Plain-text description of when this lesson applies."
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "maxItems": 12,
+          "default": [],
+          "description": "Retrieval keywords. Keep narrow; three is usually enough."
+        },
+        "targets": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "operator": { "type": "string" },
+              "role": { "type": "string" },
+              "skill": { "type": "string" }
+            },
+            "minProperties": 1
+          },
+          "default": [],
+          "description": "Operator / role / skill globs that scope retrieval. Empty means anyone."
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": true,
+          "default": {},
+          "description": "Vendor-specific trigger predicates. Standard fields above MUST NOT be redefined here."
+        }
+      }
+    },
+    "outcome": {
+      "enum": ["success", "failure", "mixed"],
+      "description": "Whether the source run succeeded, failed, or the lesson is conditional across runs."
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["kind", "ref"],
+        "additionalProperties": false,
+        "properties": {
+          "kind": {
+            "enum": ["run", "conversation", "work-item", "audit", "wiki-page"],
+            "description": "What the evidence reference points to. 'audit' = AIP-7 governance record."
+          },
+          "ref": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256,
+            "description": "Opaque id or path the host can resolve. Never free text."
+          },
+          "note": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "One-line factual note about the event — not the lesson."
+          }
+        }
+      },
+      "description": "Provenance — at least one evidence entry MUST resolve to a real run, conversation, work item, audit, or wiki page in the host's indices."
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "default": 0.5,
+      "description": "Author's confidence in [0,1]. Default 0.5 at first sighting. Runtimes weigh this against observed counts."
+    },
+    "success_count": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Times the lesson 'worked' when applied. Maintained by the runtime; author-supplied values are initial only."
+    },
+    "failure_count": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Times the lesson's claim was contradicted. Maintained by the runtime; author-supplied values are initial only."
+    },
+    "supersedes": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+      },
+      "default": [],
+      "description": "Slugs of lessons this lesson replaces. Supersession is explicit, never silent. Each cited slug MUST exist on disk."
+    },
+    "expires_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Soft TTL (ISO 8601). Past this instant, retrieval treats the lesson as absent by default."
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": {},
+      "description": "Vendor-specific extensions under namespaced keys (metadata.<vendor>.<field>). Standard fields MUST NOT be redefined."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "outcome": { "const": "failure" } }
+      },
+      "then": {
+        "description": "A failure-only lesson is permitted with success_count=0 and failure_count>=1, but at least one evidence entry MUST be present (covered by the global minItems constraint)."
+      }
+    }
+  ]
+}

package/dist/specs/resources/aip-12/draft/PLAYBOOK.schema.json

@@ -0,0 +1,349 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentproto.sh/schemas/aip-12/PLAYBOOK.schema.json",
+  "title": "PLAYBOOK.md frontmatter (AIP-12)",
+  "description": "Validates the YAML frontmatter portion of an AIP-12 PLAYBOOK.md overlay manifest.",
+  "type": "object",
+  "required": [
+    "schema",
+    "slug",
+    "title",
+    "kind",
+    "lock_check",
+    "evidence",
+    "status"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "const": "playbooks/v1"
+    },
+    "slug": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 80,
+      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "entry": {
+      "type": "string",
+      "description": "Optional path to the entry file exposing definePlaybook. Defaults to playbook.ts."
+    },
+    "targets": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/target"
+      },
+      "deprecated": true,
+      "description": "DEPRECATED in favor of `selector`. Legacy axis-ambiguous binding: runtimes compile each entry into a selector (kind 'operator' refs match BOTH the identity and the role axis — see AIP-12 §Selector binding). Kept valid forever; new files SHOULD declare `selector` instead."
+    },
+    "selector": {
+      "$ref": "#/$defs/selector",
+      "description": "Typed attachment binding evaluated against the subject's dimensions. Wins over `targets`/`binds_operator` when present."
+    },
+    "kind": {
+      "enum": [
+        "overlay",
+        "block-replacement"
+      ],
+      "default": "overlay"
+    },
+    "block": {
+      "type": "string",
+      "description": "Required when kind is 'block-replacement' — the named persona block to swap.",
+      "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$"
+    },
+    "priority": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100,
+      "default": 50
+    },
+    "lock_check": {
+      "type": "array",
+      "description": "Locked persona traits this overlay MUST NOT modify. Author intent — runtime enforces independently.",
+      "items": {
+        "$ref": "#/$defs/traitId"
+      },
+      "default": []
+    },
+    "ttl": {
+      "type": "string",
+      "description": "Optional ISO 8601 duration. Auto-archives at updated_at + ttl.",
+      "pattern": "^P(?:\\d+Y)?(?:\\d+M)?(?:\\d+W)?(?:\\d+D)?(?:T(?:\\d+H)?(?:\\d+M)?(?:\\d+S)?)?$"
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/evidenceItem"
+      }
+    },
+    "status": {
+      "enum": [
+        "shadow",
+        "active",
+        "archived"
+      ],
+      "default": "shadow"
+    },
+    "supersedes": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/slug"
+      },
+      "default": []
+    },
+    "history": {
+      "type": "array",
+      "description": "Append-only audit trail of deltas, promotions, and archivals applied to this playbook.",
+      "items": {
+        "$ref": "#/$defs/historyEntry"
+      },
+      "default": []
+    },
+    "binds_operator": {
+      "type": "string",
+      "description": "DEPRECATED as a binding — provenance only when `selector` is present. Without `selector`, runtimes compile it like a kind 'operator' target (matches BOTH identity and role axes).",
+      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$",
+      "deprecated": true
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
+      "default": []
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": {},
+      "description": "Vendor extensions go under metadata.<vendor>."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "block-replacement"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "required": [
+          "block"
+        ]
+      }
+    },
+    {
+      "anyOf": [
+        {
+          "required": [
+            "targets"
+          ]
+        },
+        {
+          "required": [
+            "selector"
+          ]
+        }
+      ]
+    }
+  ],
+  "$defs": {
+    "slug": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 80,
+      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
+    },
+    "traitId": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 64,
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "target": {
+      "type": "object",
+      "required": [
+        "kind",
+        "ref"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "enum": [
+            "operator",
+            "role",
+            "skill",
+            "runtime"
+          ]
+        },
+        "ref": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Slug, glob, or qualified path. Examples: 'role/companion', 'operator/alice', 'skill/research', 'operator/*'."
+        }
+      }
+    },
+    "evidenceItem": {
+      "type": "object",
+      "required": [
+        "kind",
+        "ref"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "enum": [
+            "run",
+            "conversation",
+            "work-item",
+            "reflection",
+            "human"
+          ]
+        },
+        "ref": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500
+        },
+        "note": {
+          "type": "string",
+          "maxLength": 1000
+        }
+      }
+    },
+    "historyEntry": {
+      "type": "object",
+      "required": [
+        "at",
+        "kind",
+        "summary"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "kind": {
+          "enum": [
+            "created",
+            "delta",
+            "promoted",
+            "archived",
+            "superseded",
+            "lock-violation"
+          ]
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1000
+        },
+        "source": {
+          "type": "string",
+          "description": "Pointer to the run/reflection/governance ticket that produced this entry."
+        },
+        "by": {
+          "type": "string",
+          "description": "User id, agent id, or system identifier responsible for the entry."
+        },
+        "gate": {
+          "enum": [
+            "a-b",
+            "scorer",
+            "human",
+            "governance"
+          ],
+          "description": "For kind='promoted', the gate that passed."
+        }
+      }
+    },
+    "selector": {
+      "type": "object",
+      "minProperties": 1,
+      "description": "Short form: axis keys (identity, role, position, capability, or host-registered) mapping to a ref or ref list — AND across keys, OR within a list. Long form: explicit `allOf`/`anyOf` selector-term lists for OR across axes. An asset that wants every subject in scope says so explicitly with `\"*\"`; an empty selector matches nothing.",
+      "properties": {
+        "allOf": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/selectorTerm"
+          }
+        },
+        "anyOf": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/selectorTerm"
+          }
+        }
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/selectorRefs"
+      }
+    },
+    "selectorTerm": {
+      "type": "object",
+      "required": [
+        "axis",
+        "anyOf"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "axis": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        },
+        "anyOf": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/selectorRef"
+          }
+        }
+      }
+    },
+    "selectorRefs": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/selectorRef"
+        },
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/selectorRef"
+          }
+        }
+      ]
+    },
+    "selectorRef": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "description": "Axis value slug, prefixed ref (e.g. 'role/sales-rep'), or '*' (any present value)."
+    }
+  }
+}