diff --git a/conformance/grammar/kp-pack.schema.json b/conformance/grammar/kp-pack.schema.json index 85e3181..ad9b147 100644 --- a/conformance/grammar/kp-pack.schema.json +++ b/conformance/grammar/kp-pack.schema.json @@ -386,6 +386,11 @@ "type": "object", "additionalProperties": true, "description": "AI note-taking metadata." + }, + "extensions": { + "type": "object", + "additionalProperties": true, + "description": "Extension lane for experimental or implementation-specific manifest metadata. Consumers MUST ignore unrecognized extension content." } }, "allOf": [ diff --git a/spec/CHANGELOG.md b/spec/CHANGELOG.md index f6a3eef..9567fd4 100644 --- a/spec/CHANGELOG.md +++ b/spec/CHANGELOG.md @@ -5,6 +5,20 @@ --- +## v0.7.4 — 2026-04-16 + +**Manifest extension lane — standardizes where experiments belong without widening the core schema.** + +### Added +- **`extensions`** (PACK.yaml, optional object) — Explicit lane for experimental or implementation-specific manifest metadata. Root-level unknown fields remain invalid; experiments now belong under `extensions`. + +### Changed +- **CORE.md** — Documents the manifest root as closed and defines the `extensions` object as the sanctioned compatibility lane. +- **SPEC.md** — Adds example manifest usage and guidance that experimental fields such as `ai_brief` belong under `extensions`, not at the manifest root. +- **Schema** — Adds `extensions` as an allowed top-level object while preserving `additionalProperties: false` at the manifest root. + +--- + ## v0.7.3 — 2026-04-12 **Archive format — sealed, hashed, versioned single-file transport for Knowledge Packs.** diff --git a/spec/CORE.md b/spec/CORE.md index e31269a..6d9ba39 100644 --- a/spec/CORE.md +++ b/spec/CORE.md @@ -94,9 +94,28 @@ PACK.yaml is a YAML file declaring pack identity and configuration. The normativ | `tags` | array | Topical tags for discovery and classification. Strict kebab-case (`^[a-z0-9]+(-[a-z0-9]+)*$`), unique | | `views` | array | View declarations with `name`, `file`, `purpose`, `display_as` (all required), `hint` (optional). Voice views add `voice` (boolean), `duration` (string, e.g. `~90 seconds`), `pace` (enum: `brisk`, `measured`, `deliberate`). When `voice` is `true`, `duration` and `pace` are REQUIRED. | | `tier` | enum | `hub`, `detail`, `standalone` | +| `extensions` | object | Extension lane for experimental or implementation-specific manifest metadata. Consumers ignore unknown extension content. | The full set of optional fields and conditional constraints is defined in the JSON Schema. Key conditionals: when `tier` is `hub`, `sub_packs` is REQUIRED; when `sensitivity` is `confidential` or `restricted`, `channels` MUST NOT contain `public` or `org`; when `sensitivity` is `internal`, `channels` MUST NOT contain `public`; when a view declares `voice: true`, `duration` and `pace` are REQUIRED on that view entry. +### Manifest Extensions + +KP:1 keeps the manifest root closed: fields not defined by the schema are invalid. Experimental or implementation-specific metadata MUST live under the optional `extensions` object instead of appearing as new top-level keys. + +Consumers MUST ignore extension content they do not understand. Extension content MUST NOT redefine the semantics of core KP fields or relax core validation rules. + +Extension names and shapes are defined by their producers, not by KP:1. The `ai_brief` payload below is one such producer-defined example. + +Example: + +```yaml +extensions: + ai_brief: + version: 1 + verdict: acceptable + headline: "Strong base attribution, but provenance gap remains" +``` + ### Example ```yaml @@ -107,6 +126,11 @@ author: Jane Chen confidence: scale: sherman_kent normalize: true +extensions: + ai_brief: + version: 1 + verdict: acceptable + headline: "Strong base attribution, but provenance gap remains" ``` --- diff --git a/spec/SPEC.md b/spec/SPEC.md index dc1f6be..e112904 100644 --- a/spec/SPEC.md +++ b/spec/SPEC.md @@ -317,6 +317,12 @@ notes: # AI note-taking metadata (see spec/NOTES participants: [] # Meeting participants disclosed: false # Was AI note-taking disclosed to participants? consent: null # Required for mode: passive — obtained | declined | pending + +extensions: # Experimental / implementation-specific manifest metadata + ai_brief: # Example extension payload (not core KP:1) + version: 1 + verdict: acceptable + headline: "Strong base attribution, but provenance gap remains" ``` ### Version Semantics @@ -398,6 +404,14 @@ channels: [org, public] The spec defines the `channels` field and its vocabulary. How channels map to infrastructure is a deployment concern. +### 3.2 Manifest Extensions + +The PACK.yaml root is intentionally closed. New or experimental manifest keys MUST NOT be added at the top level unless and until they are standardized by a future KP revision. + +Implementation-specific or experimental metadata MUST live under the optional `extensions` object. Consumers MUST ignore extension content they do not understand. Extension content MUST NOT override or redefine the meaning of core KP fields. + +The example payload shown earlier (`ai_brief`) is illustrative — extension names and shapes are defined by their producers, not by KP:1. This creates a narrow compatibility lane: tools can ship experiments without forcing a schema break or prematurely promoting the payload into the core standard. + --- ## 4. claims.md — The Primary File