@openwop/spec-artifacts 2.0.0-rc.0

package/schemas/orchestrator-decision.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/orchestrator-decision.schema.json",
+  "title": "OrchestratorDecision",
+  "description": "Routing decision emitted by an orchestrator-supervisor node. Carried in the `runOrchestrator.decided` event payload's `decision` field (run-orchestrator-decided-event.schema.json). Three canonical kinds form a closed canonical enum at the protocol layer: `'next-worker'` (continue dispatch), `'ask-user'` (route a question to the human party), `'terminate'` (clean run completion). Vendor-extension decision kinds MAY ship under `vendor.<host>.<kind>` per host-extensions.md but conformance MUST validate against the closed canonical set. See RFC 0006 §C.",
+  "type": "object",
+  "required": ["kind"],
+  "oneOf": [
+    {
+      "title": "NextWorkerDecision",
+      "description": "Dispatch one or more next workers. Phase-5 hosts MAY treat the `nextWorkerIds` array as length-1 only and ignore the tail; Phase-6 hosts (RFC 0007 / `core.dispatch`) SHOULD honor full fan-out semantics. The interpretation of array entries (node-id vs agent-id) is left to host capability advertisement; see RFC 0006 §C unresolved-question 1.",
+      "type": "object",
+      "required": ["kind", "nextWorkerIds"],
+      "properties": {
+        "kind": { "const": "next-worker" },
+        "nextWorkerIds": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          },
+          "description": "Ordered list of worker node-ids OR agent-ids to dispatch. Hosts that interpret entries as node-ids dispatch in DAG order; hosts that interpret as agent-ids resolve to nodes via the run's static DAG."
+        },
+        "nextWorkerInputs": {
+          "type": "array",
+          "items": { "type": "object" },
+          "description": "RFC 0126 (data-parallel fan-out). OPTIONAL, index-aligned with `nextWorkerIds`: `nextWorkerInputs[i]` is a per-child input object (child input variable names → values) projected into the child dispatched for `nextWorkerIds[i]`, over the RFC 0022 `inputMapping`/`perWorkerInputMappings` projection (per-item value WINS on key collision). Enables fanning ONE `childWorkflowId` over N runtime items with distinct inputs (the map-over-collection pattern). When present, `nextWorkerInputs.length` MUST equal `nextWorkerIds.length` (a host MUST fail the dispatch node with `validation_error` and dispatch NO child otherwise — length is not JSON-Schema-enforceable, so this is a runtime MUST). Gated on `capabilities.dispatch.perItemInput`: a host NOT advertising it, upon receiving a non-empty `nextWorkerInputs`, MUST fail closed with `validation_error` and MUST NOT silently drop-and-dispatch N identical children (the correctness/spend hazard this closes). Replay-safe: rides the recorded `runOrchestrator.decided` event, re-read verbatim on `:fork`, never recomputed (frozen at decision time). A `sensitive`/secret per-item value MUST NOT appear here in plaintext (use the secret channel). See `node-packs.md` §core.dispatch."
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "RFC 0039 §A — supervisor's stated confidence in this decision, in [0, 1]. Optional; absent means 'no opinion stated' (NOT low confidence). Hosts advertising `capabilities.multiAgent.executionModel.version >= 2` MUST honor a confidence floor (spec floor 0.5; operator-stricter via `confidenceEscalationFloor`): a decision with `confidence` below the floor MUST escalate via clarify-or-escalate interrupt instead of executing. Pre-Phase-2 hosts ignore the field per forward-compat."
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "title": "AskUserDecision",
+      "description": "Route a human-targeted question. Hosts that adopted RFC 0005 (Phase 4) SHOULD route through `conversation.exchange`; pre-RFC-0005 hosts MAY surface as a `'clarification'` interrupt. The transport is host-policy; the protocol-layer decision shape is the same.",
+      "type": "object",
+      "required": ["kind", "prompt"],
+      "properties": {
+        "kind": { "const": "ask-user" },
+        "prompt": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-targeted question. Free-form text; the protocol does NOT structure the prompt further."
+        }
+      },
+      "additionalProperties": false
+    },
+    {
+      "title": "TerminateDecision",
+      "description": "Clean run termination driven by orchestrator judgement. Distinct from `run.failed` (uncaught executor error) and `run.cancelled` (operator cancellation) — see RFC 0006 §H. The terminate `reason?` is informational; the protocol does NOT close the value enum.",
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": { "const": "terminate" },
+        "reason": {
+          "type": "string",
+          "description": "Optional free-form rationale captured for audit/debug. Common values: `'goal-reached'`, `'max-iterations'`, `'unrecoverable-error'`. Spec does NOT close this enum.",
+          "minLength": 1
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "RFC 0039 §A — supervisor's stated confidence in this termination decision, in [0, 1]. Optional; absent means 'no opinion stated' (NOT low confidence). Hosts advertising `capabilities.multiAgent.executionModel.version >= 2` MUST honor a confidence floor as documented on NextWorkerDecision.confidence above; the same MUST applies to TerminateDecision because a confidently-wrong terminate is the same class of failure as a confidently-wrong dispatch."
+        },
+        "successCriteria": {
+          "type": "array",
+          "description": "RFC 0090 (`multiAgent.executionModel.version >= 6`). Optional structured convergence record — the conditions the supervisor judged when terminating. Content-free: criterion keys + booleans only, never result content. When present, a terminate with any `met: false` entry signals a give-up (NOT goal-satisfied); consumers MUST NOT treat such a run as a success. Absent ⇒ today's free-text `reason` semantics, unchanged.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["key", "met"],
+            "properties": {
+              "key": { "type": "string", "minLength": 1, "description": "Criterion identifier (e.g. `goal-answered`)." },
+              "met": { "type": "boolean", "description": "Whether the supervisor judged this criterion satisfied." }
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  ]
+}

package/schemas/org-chart-responsibility-view.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/org-chart-responsibility-view.schema.json",
+  "title": "OrgChartResponsibilityView",
+  "description": "RFC 0087 §D. Response body for `GET /v1/agents/org-chart/{departmentId}` — one department's subtree + the derived responsibility roll-up (the union of its members' RFC 0086 workflow portfolios, recursively through sub-departments unless `?recursive=false`). A read-only VIEW computed from live roster entries: it grants nothing (§B `org-position-no-authority-escalation`) and stores nothing. Tenant-scoped per RFC 0074.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["department", "members", "responsibilities"],
+  "properties": {
+    "department": {
+      "$ref": "./agent-org-chart.schema.json#/$defs/Department",
+      "description": "The department this view is rooted at."
+    },
+    "members": {
+      "type": "array",
+      "items": { "$ref": "./agent-org-chart.schema.json#/$defs/Member" },
+      "description": "The department's members (and, by default, its sub-departments' members)."
+    },
+    "responsibilities": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "The union of the members' RFC 0086 `workflows[]` portfolios — 'what this department is collectively responsible for'. Deduped; descriptive only."
+    }
+  }
+}

package/schemas/pack-lockfile.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/pack-lockfile.schema.json",
+  "title": "PackLockfile",
+  "description": "Reproducible-build lockfile pinning resolved versions of every pack a workspace depends on. Per spec/v1/node-packs.md §\"Dependency resolution + lockfile\". A workspace records its lockfile alongside its workflow definitions; on subsequent installs the registry resolver MUST honor the lockfile's exact versions rather than re-running semver resolution. This guarantees that a workflow that ran against `vendor.openwop.rust-hello@1.0.0` will still run against `1.0.0` even after `1.0.1` is published.",
+  "type": "object",
+  "required": ["lockfileVersion", "generatedAt", "packs"],
+  "properties": {
+    "lockfileVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Lockfile schema version. Bumped when the lockfile structure changes incompatibly. v1.0 ships at lockfileVersion 1."
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp the lockfile was written. Used for audit + cache-bust diagnostics; resolvers MUST NOT use this for resolution decisions."
+    },
+    "registry": {
+      "type": "string",
+      "format": "uri",
+      "description": "Optional source-of-truth registry URL the resolved versions were fetched from (e.g., `https://packs.openwop.dev`). Multi-registry workspaces include this for audit. Single-registry workspaces MAY omit."
+    },
+    "packs": {
+      "type": "array",
+      "description": "Resolved pack records, one per pack referenced (transitively) by the workspace's workflow definitions. Order is informational only; resolvers MUST NOT rely on order. Empty arrays are allowed (a workspace with no packs).",
+      "items": { "$ref": "#/$defs/ResolvedPack" }
+    },
+    "overrides": {
+      "type": "object",
+      "description": "Optional override map per `node-packs.md` §\"Transitive dependency resolution\" §\"Override pinning\". Keys are pack names; values are exact pinned versions that resolvers MUST honor ahead of normal range resolution. The override version MUST still satisfy at least one parent's declared range — silently breaking the contract fails with `pack_dependency_conflict`. Use sparingly: security patches, conflict resolution, supply-chain pinning.",
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 64,
+        "description": "Exact pinned version that overrides this pack's normal range resolution."
+      }
+    },
+    "fallbackRegistries": {
+      "type": "array",
+      "items": { "type": "string", "format": "uri" },
+      "uniqueItems": true,
+      "description": "Optional ordered list of fallback registry base URLs per `registry-operations.md` §\"Registry mirror + federation\". When a pack is not found in the primary `registry`, resolvers MUST consult each fallback in order. The first registry returning a 200 for the version manifest wins. Trust roots are per-registry — a fallback being listed here does NOT imply trust transitivity. Each pack's signature is verified against the issuing registry's `signingKeys[]` allow-list."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "ResolvedPack": {
+      "type": "object",
+      "required": ["name", "version", "integrity"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 3,
+          "maxLength": 256,
+          "pattern": "^(core|vendor|community|private|local)\\.[a-z0-9][a-z0-9.-]*$",
+          "description": "Pack name per node-packs.md §\"Manifest format\" `name`. Reverse-DNS-style; namespace prefix is one of the canonical tiers."
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "Resolved exact version (no ranges). Semver MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]. The resolver MUST pin to this exact version on subsequent installs."
+        },
+        "resolved": {
+          "type": "string",
+          "format": "uri",
+          "description": "Optional canonical URL the tarball was fetched from. Audit aid; resolvers MUST verify the `integrity` field even if this URL is present."
+        },
+        "integrity": {
+          "type": "string",
+          "pattern": "^sha256-[A-Za-z0-9+/]{43}=$",
+          "description": "Subresource-integrity-style hash of the tarball: literal `sha256-` followed by 43-char base64-encoded SHA-256 digest with trailing `=` padding. Resolvers MUST verify the downloaded tarball's SHA-256 matches before extraction. Hash mismatch MUST fail the install with `pack_integrity_mismatch`."
+        },
+        "signature": {
+          "type": "object",
+          "description": "Optional pack signature material (Ed25519 per node-packs.md §Signing). When present, resolvers MUST verify the signature against the publisher's advertised public key.",
+          "required": ["algorithm", "publicKey", "value"],
+          "properties": {
+            "algorithm": { "type": "string", "enum": ["ed25519"] },
+            "publicKey": { "type": "string", "minLength": 1, "description": "Base64-encoded Ed25519 public key bytes." },
+            "value": { "type": "string", "minLength": 1, "description": "Base64-encoded Ed25519 signature over the tarball." }
+          },
+          "additionalProperties": false
+        },
+        "dependencies": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          },
+          "description": "Pinned versions for this pack's `dependencies` (per its manifest). Each key is a pack name; each value is the resolved exact version. Pinned recursively — a transitively-installed pack appears once in the top-level `packs[]` array AND as a value in each parent's `dependencies` map."
+        },
+        "peerDependencies": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          },
+          "description": "Echo of this pack's manifest `peerDependencies` for audit. Resolvers MUST verify that the host's `/.well-known/openwop` advertises every key listed here (per host-capabilities.md §\"Capability negotiation\"). Lockfile records the host-capability values the workspace committed to at lockfile-write time; mismatches at install time MAY warn (host advertises richer set) but MUST fail if a peer-dep is missing."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/prompt-kind.schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/prompt-kind.schema.json",
+  "title": "PromptKind",
+  "description": "Role a PromptTemplate plays when composed into an LLM call. Shared $def referenced by every schema that names a prompt kind. Adding a kind here is the single edit needed to introduce one across the corpus. See spec/v1/prompts.md §\"PromptKind\" for the canonical semantics of each value, and RFC 0027 for the rationale behind the four-value choice (vs. an open-ended string).\n\nKind semantics:\n- system: behavior + output discipline; composed as the LLM's system message.\n- user: per-call task prompt; composed as the LLM's user message; the surface variable substitution targets.\n- few-shot: example bodies prepended to the user message OR injected as alternating user/assistant turns per host policy.\n- schema-hint: structured-output schema description injected into the system or user message at compose time.",
+  "type": "string",
+  "enum": ["system", "user", "few-shot", "schema-hint"]
+}

package/schemas/prompt-pack-manifest.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/prompt-pack-manifest.schema.json",
+  "title": "PromptPackManifest",
+  "description": "Manifest for a published OpenWOP prompt pack — `pack.json` at the pack root with `kind: \"prompt\"`. Peer to `node-pack-manifest.schema.json` (RFC 0003) and `workflow-chain-pack-manifest.schema.json` (RFC 0013); disjoint from both via the `kind` discriminator. See `spec/v1/prompts.md` §\"Discovery & distribution\" for the canonical contract and RFC 0028 §B for the rationale.\n\nPrompt packs distribute curated PromptTemplate collections via the same signed-tarball + Ed25519 + SRI pipeline that already serves node and workflow-chain packs. When a host installs a prompt pack and advertises `capabilities.prompts.packsSupported: true`, the templates appear in `GET /v1/prompts` with `meta.source: \"pack\"` + `meta.packName` + `meta.packVersion`.",
+  "type": "object",
+  "required": [
+    "name",
+    "version",
+    "kind",
+    "engines",
+    "prompts"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Reverse-DNS pack name per `node-packs.md` §Naming. Reserved scopes are identical (`core.*` / `vendor.<org>.*` / `community.<author>.*` / `private.<host>.*`). Mirror of `workflow-chain-pack-manifest.schema.json#/properties/name`.",
+      "pattern": "^(core|vendor|community|private)\\.[a-z][a-z0-9_-]*(\\.[a-z][a-zA-Z0-9_-]*)+$",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "version": {
+      "type": "string",
+      "description": "Pack-level SemVer 2.0.0.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+    },
+    "kind": {
+      "type": "string",
+      "const": "prompt",
+      "description": "Pack kind discriminator. MUST be the literal string `\"prompt\"` for this schema. Manifests carrying `kind: \"node\"` validate against `node-pack-manifest.schema.json`; `kind: \"workflow-chain\"` against `workflow-chain-pack-manifest.schema.json`."
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 1024
+    },
+    "author": {
+      "type": "string"
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX license identifier (e.g., `Apache-2.0`)."
+    },
+    "homepage": {
+      "type": "string",
+      "format": "uri"
+    },
+    "repository": {
+      "type": "string",
+      "format": "uri"
+    },
+    "keywords": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 64
+      },
+      "maxItems": 50
+    },
+    "engines": {
+      "type": "object",
+      "required": [
+        "openwop"
+      ],
+      "properties": {
+        "openwop": {
+          "type": "string",
+          "description": "SemVer range — which openwop protocol versions this pack works against (e.g., `>=1.1.0 <2.0.0`)."
+        }
+      },
+      "additionalProperties": true,
+      "$comment": "Open by design — packs MAY advertise extra engine constraints (`node`, `python`, etc.) that consumer hosts ignore but operator tooling consumes. Mirrors workflow-chain-pack-manifest."
+    },
+    "dependencies": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Other packs whose templates this pack's templates reference (e.g., via cross-pack `PromptRef.libraryId` lookups, or via a future `extends:` inheritance syntax). Map of pack name → SemVer range. Install-time validation MUST resolve every entry before accepting the install; an unresolvable entry rejects with `prompt_pack_dependency_unresolvable`. The *semantics* of cross-pack composition (template inheritance, transitive `dependencies` closure) are out of scope for RFC 0028 and defer to a follow-up RFC; this RFC ships the field + the install-time resolve MUST only. Shape mirrors `workflow-chain-pack-manifest.schema.json#/properties/dependencies` (RFC 0013)."
+    },
+    "prompts": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "./prompt-template.schema.json"
+      },
+      "description": "PromptTemplate entries per RFC 0027 §A. Each MUST have a unique `(templateId, version)` pair within the pack. Hosts installing this pack expose the templates at `GET /v1/prompts` with `meta.source: \"pack\"` + `meta.packName: <this pack's name>` + `meta.packVersion: <this pack's version>` populated automatically (RFC 0028 §C)."
+    },
+    "signing": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional signing metadata. Reuses the Ed25519 + SRI flow from `node-packs.md §Signing` unchanged. Hosts installing this pack MUST verify the signature before accepting any of `prompts[]` per `registry-operations.md §\"Signature verification\"`.",
+      "properties": {
+        "publicKeyRef": {
+          "type": "string",
+          "description": "Path inside the tarball to the Ed25519 public key (PEM-encoded)."
+        },
+        "signatureRef": {
+          "type": "string",
+          "description": "Path to the detached signature over `pack.json`."
+        },
+        "method": {
+          "type": "string",
+          "enum": [
+            "manual",
+            "sigstore"
+          ]
+        }
+      }
+    }
+  },
+  "patternProperties": {
+    "^(x-|vendor\\.)": {
+      "description": "Vendor / host extension escape hatch (RFC 0138). A property matching `^(x-|vendor\\.)` is a HOST EXTENSION: its semantics are unspecified by this protocol, and a consumer that does not recognize one MUST ignore it rather than reject the pack. Resolves the contradiction in `host-extensions.md` §\"Vendor-prefixed namespaces\", which requires a client receiving an unknown vendor-prefixed field to treat it as opaque — a field that `additionalProperties: false` previously made impossible to carry. SECURITY: an extension value is PACK-AUTHORED, therefore untrusted; \"ignore\" means ignore. See `node-packs.md` §\"Vendor extensions on pack manifests\" and the `pack-manifest-extension-opaque` invariant."
+    }
+  }
+}

package/schemas/prompt-ref.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/prompt-ref.schema.json",
+  "title": "PromptRef",
+  "description": "Reference to a PromptTemplate. Two equivalent forms are accepted: a compact stringy URI (`prompt:templateId[@version]`) and a structured object form. The stringy form is canonical for inline use in WorkflowNode.config and AgentManifest.promptOverrides; the object form is canonical when libraryId disambiguation, variable overrides, or pinned versions need to be expressed explicitly. See spec/v1/prompts.md §\"PromptRef\" for the canonical contract and RFC 0027 §B for the rationale.\n\nResolution semantics (host responsibility): the host looks up the referenced template in its library (host built-ins + installed packs + user templates, gated by capabilities.prompts.*). When no `version` is given, the latest version wins. When two installed packs ship the same templateId, the stringy form is rejected with `prompt_ref_ambiguous` and consumers MUST use the object form with `libraryId` to disambiguate (RFC 0028 §B \"Conflict resolution\").",
+  "oneOf": [
+    {
+      "type": "string",
+      "pattern": "^prompt:[a-z0-9][a-z0-9._-]{0,127}(@\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?)?$",
+      "description": "Compact stringy form: `prompt:<templateId>[@<version>]`. Examples: `prompt:writer`, `prompt:writer@1.2.0`, `prompt:vendor.acme.writer.v2@2.0.0`."
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["templateId"],
+      "description": "Structured object form. Use when `libraryId` disambiguation, per-reference variable overrides, or version pinning is needed.",
+      "properties": {
+        "libraryId": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$",
+          "description": "Library scope. Per RFC 0028, the host's default library is identified by `capabilities.prompts.library.id`; pack-sourced templates resolve via the installed pack's `name`."
+        },
+        "templateId": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$",
+          "description": "Same pattern as PromptTemplate.templateId."
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$",
+          "description": "Pinned SemVer. When omitted, the host resolves the latest version available in the named library."
+        },
+        "variableOverrides": {
+          "type": "object",
+          "description": "Per-reference variable bindings, applied at composition time. Take precedence over node-input bindings (matching the four-layer resolution chain in RFC 0029 §A). Bindings are validated against PromptTemplate.variables before composition."
+        }
+      }
+    }
+  ]
+}

package/schemas/prompt-template.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/prompt-template.schema.json",
+  "title": "PromptTemplate",
+  "description": "Canonical wire shape for a named, versioned, variable-bound prompt body referenced by workflow nodes and agent manifests. See spec/v1/prompts.md §\"PromptTemplate\" for the canonical contract, RFC 0027 for the rationale, and prompt-ref.schema.json for the reference type that points at instances of this shape. Variable interpolation MUST use Mustache-compatible `{{varName}}` placeholders; unresolved required variables MUST cause the node to fail with `prompt_variable_unresolved`; unresolved optional variables render as the empty string per RFC 0027 §A.\n\nThe `text` field MAY contain `<UNTRUSTED>...</UNTRUSTED>` markers verbatim — hosts MUST preserve them through composition per SECURITY/threat-model-prompt-injection.md. Variables sourced from `secret` MUST be replaced with `[REDACTED:<secretId>]` markers in any observability output (e.g., `prompt.composed` events) per SECURITY/threat-model-secret-leakage.md §SR-1.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["templateId", "version", "kind", "text"],
+  "properties": {
+    "templateId": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$",
+      "description": "Stable identifier. Convention: vendor-prefixed for portable templates (`vendor.acme.writer.v2`) or unprefixed for host-resident templates (`writer`). Same naming discipline as node-pack typeIds (host-extensions.md §\"Canonical-prefix table\")."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$",
+      "description": "Semantic Versioning 2.0.0. Bumping major implies a breaking variable-schema or text change; consumers MUST pin to a specific version via PromptRef.version if they care about exact bodies."
+    },
+    "kind": {
+      "$ref": "./prompt-kind.schema.json",
+      "description": "Role this template plays when composed into an LLM call. A node MAY reference one template of each kind. Relative $ref resolves to the shared enum file for redocly's local-file walker; Ajv resolves it equivalently via the schema registry."
+    },
+    "text": {
+      "type": "string",
+      "maxLength": 65536,
+      "description": "Template body. Mustache-compatible `{{varName}}` placeholders are substituted at compose time using bindings from PromptVariable.source + variableOverrides. Hosts MAY cap below 65536 via capabilities.prompts.maxTemplateBytes, but MUST NOT exceed it."
+    },
+    "name": {
+      "type": "string",
+      "maxLength": 200,
+      "description": "Human-readable display name surfaced in authoring UIs and template pickers."
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 2000,
+      "description": "One-paragraph description of what the template is for. Surfaced in authoring UI hover-text and library-list cards."
+    },
+    "variables": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/PromptVariable" },
+      "description": "Typed interpolation slots. Hosts MUST validate runtime bindings against this array before composing. A `{{varName}}` placeholder that has no matching entry in `variables[]` MAY appear (treated as an optional variable with source `input` and no default) — hosts SHOULD warn at install time."
+    },
+    "modelHints": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Non-normative authoring hints. Hosts MAY surface these in editor UI (default temperature, suggested model class). They do NOT override per-node config or per-run RunOptions.configurable values.",
+      "properties": {
+        "modelClass": {
+          "type": "string",
+          "description": "Per AgentRef.modelClass enum + vendor extensions (e.g., `reasoning`, `writing`, `vendor.openwop.creative-writing`)."
+        },
+        "temperature": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2,
+          "description": "Suggested sampling temperature."
+        },
+        "maxTokens": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Suggested max-tokens ceiling."
+        },
+        "envelopeType": {
+          "type": "string",
+          "description": "Suggested AI Envelope kind to use with this template, per RFC 0021. Opaque string in v1.x; future RFC MAY cross-validate against capabilities.supportedEnvelopes."
+        }
+      }
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "maxLength": 64 },
+      "maxItems": 32,
+      "description": "Free-form classification labels. Used by authoring UIs to group templates; not normative."
+    },
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Provenance + lifecycle metadata. Optional; hosts SHOULD populate it for any persistent storage. When `source: \"pack\"`, the host MUST populate `packName` + `packVersion` so clients can disambiguate templates that share a `templateId` across multiple installed packs (per RFC 0028 §B \"Conflict resolution\").",
+      "properties": {
+        "author": { "type": "string", "description": "Free-form author identifier (handle, email, etc.)." },
+        "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC timestamp of initial creation." },
+        "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC timestamp of most recent update." },
+        "source": {
+          "type": "string",
+          "enum": ["host", "pack", "user"],
+          "description": "Provenance discriminator. `host`: ships with the host's built-in library; immutable. `pack`: installed via RFC 0028 prompt pack; immutable; MUST carry `packName` + `packVersion`. `user`: created at run time via mutating endpoints; mutable iff `capabilities.prompts.mutableLibrary: true`."
+        },
+        "packName": {
+          "type": "string",
+          "pattern": "^(core|vendor|community|private)\\.[a-z][a-z0-9_-]*(\\.[a-z][a-zA-Z0-9_-]*)+$",
+          "description": "RFC 0028 §C. When `source: \"pack\"`, the installed pack's `name` (matches `PromptPackManifest.name`). Required when `source: \"pack\"`; absent otherwise. Lets clients pass a structured `PromptRef` with `libraryId` set to this value to disambiguate templates that share a `templateId` across packs."
+        },
+        "packVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$",
+          "description": "RFC 0028 §C. When `source: \"pack\"`, the installed pack's `version`. Required when `source: \"pack\"`; absent otherwise."
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "source": { "const": "pack" } }, "required": ["source"] },
+          "then": { "required": ["source", "packName", "packVersion"] }
+        }
+      ]
+    }
+  },
+  "$defs": {
+    "PromptVariable": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "type", "required"],
+      "description": "Typed interpolation slot. Bindings are validated against this declaration before composition; unresolved required slots MUST fail the node with `prompt_variable_unresolved`. Variables sourced from `secret` MUST be redacted to `[REDACTED:<secretId>]` markers in observability output per SECURITY/threat-model-secret-leakage.md §SR-1.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]{0,63}$",
+          "description": "Variable identifier. MUST match the `{{name}}` placeholder pattern in `text`. Pattern aligns with common templating engines (Mustache, Handlebars, Liquid) — no dashes, no dotted paths."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["string", "number", "boolean", "array", "object"],
+          "description": "JSON-Schema-style type hint. Hosts SHOULD validate the bound value's type against this declaration; type-mismatch MAY warn or fail per host policy (no normative MUST yet — see RFC 0027 §A)."
+        },
+        "required": {
+          "type": "boolean",
+          "description": "When true, an absent binding fails the node with `prompt_variable_unresolved`. When false, the variable renders as `defaultValue` (if present) or the empty string."
+        },
+        "source": {
+          "type": "string",
+          "enum": ["input", "variable", "secret", "context"],
+          "description": "Where the binding comes from. `input`: node input port. `variable`: run-scoped variable (`ctx.variables.get`). `secret`: BYOK secret reference — MUST be redacted in observability events per RFC 0027 §E. `context`: host-provided implicit context (current user id, run id, etc.). Default when omitted: `input`."
+        },
+        "extractPath": {
+          "type": "string",
+          "description": "JSONPath into the source. When omitted, the entire source value binds to `name`. Hosts that don't support JSONPath MAY treat this as opaque dotted-path and surface an `unsupported_extract_path` warning."
+        },
+        "defaultValue": {
+          "description": "Used when `required: false` and the source resolves to undefined. Any JSON-serializable value."
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Human-readable explanation. Surfaced in authoring UIs."
+        }
+      }
+    }
+  }
+}

package/schemas/proposal.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/proposal.schema.json",
+  "title": "Proposal",
+  "description": "RFC 0096 §B. A reviewable-learning proposal — an INERT, draft-state reusable artifact (skill/pack/template/automation) the host synthesized from run/tool traces, that MUST NOT influence the resolution, planning, or execution of any run while in any state other than `applied`. Activation is delegated to RFC 0051 approval-gate or RFC 0049 RBAC (no new authorization path). On `apply` the installed artifact MUST byte-match the last-persisted `artifact` (no silent re-synthesis). `rationale` and `provenance.sourceRunIds` are SR-1 redaction-safe (no secrets/PII). Gated on the `agents.proposals` capability.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "kind", "state", "artifact", "provenance", "owner", "createdAt"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Host-assigned identifier, stable across revisions."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["agent-pack", "workflow-chain-pack", "prompt-template", "automation"],
+      "description": "The reusable artifact kind. `agent-pack` (RFC 0003), `workflow-chain-pack` (RFC 0013), `prompt-template` (RFC 0027), `automation` (RFC 0052 scheduled job)."
+    },
+    "state": {
+      "type": "string",
+      "enum": ["draft", "revised", "applied", "rejected", "archived"],
+      "description": "Lifecycle state. Only `applied` may influence a run. `draft`/`revised` are inert; `rejected`/`archived` are terminal-inert."
+    },
+    "title": {
+      "type": "string",
+      "description": "Human-facing label. SR-1 redaction-safe."
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Plain-language justification. SR-1 redaction-safe — no secrets/PII."
+    },
+    "artifact": {
+      "type": "object",
+      "description": "The proposed artifact, shaped by `kind` (an RFC 0003 pack manifest, an RFC 0013 chain pack, an RFC 0027 template, an RFC 0052 job spec). Inert until applied. Deliberately open (`additionalProperties` not constrained here) because the payload conforms to the kind's own existing schema, validated by the host at `apply` (malformed-for-kind ⇒ 422).",
+      "$comment": "Intentionally open object — the artifact body is validated against the kind's own schema, not this envelope."
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sourceRunIds"],
+      "description": "Where the proposal came from.",
+      "properties": {
+        "sourceRunIds": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Runs whose traces produced this proposal (RFC 0040 causation-compatible). SR-1 redaction-safe."
+        },
+        "synthesizerModel": {
+          "type": "string",
+          "description": "Opaque identifier of the model/process that synthesized the draft."
+        }
+      }
+    },
+    "duplicateOf": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Existing artifact ref this proposal restates/overlaps, when `agents.proposals.duplicationDetection` is on. `null` when unknown or detection is off."
+    },
+    "owner": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tenant"],
+      "description": "RFC 0048 identity triple that owns this proposal. Redaction-safe — `principal` is an opaque id, never PII or credential material. Single-tenant hosts populate at least `tenant`.",
+      "properties": {
+        "tenant": { "type": "string", "minLength": 1, "description": "Top-level isolation boundary." },
+        "workspace": { "type": "string", "minLength": 1, "description": "Optional sub-tenant within the tenant (RFC 0048 workspace)." },
+        "principal": { "type": "string", "minLength": 1, "description": "Acting identity (user or agent) — opaque id, never PII." }
+      }
+    },
+    "activation": {
+      "type": ["object", "null"],
+      "default": null,
+      "description": "Populated only when `state: applied`: the RFC 0051 approval reference (if `activation = approval-gate`) and the resulting installed artifact ref.",
+      "additionalProperties": false,
+      "properties": {
+        "approvalId": { "type": ["string", "null"], "description": "RFC 0051 approval/gate id when activation routed through an approval gate." },
+        "installedArtifactRef": { "type": "string", "description": "Ref of the artifact installed on `apply` (RFC 0043 install path)." }
+      }
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  }
+}