Status: v0.1 (filed 2026-06-06) — Architect-authored; companion to PDR-005 v1.0 §Open question 6; in-house material per Klatch-pause Evolution-section convention (HOST 2026-05-24). Three-fire bursty-lane drafted (Fire 1 skeleton + plugin-packaging framing; Fire 2 §Decision D1-D6 substantive content; Fire 3 polish + §Consequences refinement + v0.1 final).
Date: 2026-06-06
Authors: Chief Architect (Arch)
Reviewers: PPM (PDR-005 owner), Lead Dev (implementation lane), CIO (methodology), CEO (xian)
PDR-005 v1.0 (Bring Your Own Chat, ratified 2026-06-05) commits Piper Morgan to MCP server primary + thin bespoke UI distribution. The mechanism set #5 names “context-package format negotiated with sibling projects” as an architectural commitment. PDR-005 §Open question 6 routes the specific format decision to this ADR.
The concrete need: when Piper Morgan exposes its context state to a host (MCP client like Claude Desktop, ChatGPT, Slack) or a sibling project (Klatch, future systems), or when Piper Morgan consumes context state offered by an external surface, the shape of that interchange has to be canonical and stable enough that:
PM clarified 2026-06-01 (via PA): the plugin is the canonical Anthropic-side packaging unit — config + CLAUDE.md + skills + MCP server. MCPB and hosted-MCP are NOT the packaging unit; they are deployment targets for the plugin’s MCP server component. The context-package format is what flows between the plugin’s MCP server and connected hosts/projects.
So Q6 has two layers:
config, CLAUDE.md, skills, MCP server)This ADR addresses both. Layer 1 is the load-bearing decision; layer 2 is how the format fits into the plugin’s distribution shape.
Per Architect↔Daedalus alignment brief (Architect to Janus, 2026-05-15) the cross-project alignment question is: “What is the canonical context package?” The brief asked Klatch’s read on:
Klatch paused 2026-05-20 before Daedalus’s reply landed. This ADR proceeds with in-house material per the Pattern-064 Evolution-section convention HOST lifted (2026-05-24) as the general operating norm for uncertain external-alignment dependencies. Klatch refinements fold into §Evolution when alignment resumes; the ADR does not block on Klatch reply.
Four sub-decisions inside Q6:
surface_type slot) is m-40 instance #3 in the catalog; the verb-enum-as-source-of-truth + slot-as-separable-dimension shape inherits from ADR-060 amendment’s same architectural primitive at the intent-classifier altitudeThe canonical context-package format is JSON-encoded, three-layer (envelope + body + extensions), with typed-enum capability primitives, ADR-063 READ-side error envelopes, Postel-ish forward compat, and plugin-config-declared format versions. Each sub-decision is grounded in either prior architectural commitments (PDR-005, ADR-061, ADR-063), prior cross-project alignment work (Janus brief 2026-05-15), or existing pattern catalog entries (Pattern-072, methodology-32).
Decision: All context packages are JSON-encoded text with a mandatory top-level schema_version field (MAJOR.MINOR.PATCH SemVer-flavored).
Justification:
jq a context package; you cannot jq a Protobuf blob without the schema)schema_version at the top level (NOT buried in envelope sub-fields) lets receivers route to the right deserializer before parsing the restAlternatives considered:
Trade-off acknowledged: JSON’s representation limits mean binary primitives (images, audio, large blobs) live outside the format and are carried by reference (URI / content-addressable hash). This is captured under §Consequences/Negative.
Decision: Every context package is structurally a three-field JSON object:
{
"envelope": {
"schema_version": "1.0.0",
"package_type": "capability_claim | context_slice | tool_call | tool_result | audit_event | error",
"source": {
"agent": "piper-morgan",
"host_surface": "claude_desktop | chatgpt | slack_thread | bespoke_ui | sibling_project",
"host_surface_version": "..."
},
"timestamp": "ISO-8601 UTC",
"trace_id": "stable-cross-package correlation token"
},
"body": {
/* package-type-specific payload */
},
"extensions": {
"vendor": { /* host-or-project-specific opt-in */ },
"experimental": { /* feature-flagged opt-in */ }
}
}
Justification:
envelope.package_type. Each package_type has its own body schema.Composes with: ADR-063 audit envelope read-surface (audit_event package_type’s body shape IS the ADR-063 envelope); ADR-061 LLM-touch four-element principle (the envelope IS the audit-envelope element at LLM-touch boundaries).
surface_type slotDecision: When Piper Morgan advertises a capability (PDR-005 AC-1 host-aware capability map), the package body uses the verb-enum + slot shape established by the 2026-06-06 ADR-060 amendment ratification:
{
"envelope": { "package_type": "capability_claim", ... },
"body": {
"verb": "tool.call | resource.read | prompt.complete | audit.read | surface.detect | ...",
"surface_type": "claude_desktop | chatgpt | slack_thread | bespoke_ui | sibling_project",
"claim": "available | conditionally_available | unavailable",
"conditions": { /* per-host predicates, e.g. requires_user_consent: true */ }
}
}
Justification — three reasons this shape is right:
claim: conditionally_available + conditions lets the receiver decide whether the capability applies in its environment.unavailable, the safe fallback per ADR-060 floor-first).Crucially NOT: capability is NOT a verb-object name collapsed string (tool_call_for_github_issue). That’s the #1158 failure mode this ADR + ADR-060 amendment are designed to prevent. One name collapsed, two slots separated.
Decision: Error packages (envelope.package_type == "error") use a body shape that adapts ADR-063’s user-facing audit envelope READ-surface to cross-host error surfacing. The four READ-side elements:
{
"envelope": { "package_type": "error", ... },
"body": {
/* Element 1: User-visible field set */
"error_code": "ENVELOPE_MALFORMED | CAPABILITY_UNAVAILABLE | TOOL_FAILED | RATE_LIMITED | AUTH_REQUIRED | ...",
"human_message": "Short human-readable description suitable for surfacing to the user",
"retry_hint": "transient | needs_user_action | permanent",
/* Element 2: Schema-validated at consumption — receiver verifies error envelope conforms to schema_version */
/* Element 3: Safe-fallback — if envelope is malformed, receiver treats as error_code: ENVELOPE_MALFORMED instead of crashing */
/* Element 4: JWT-bound access control */
"audit_visible": true,
"diagnostic": {
/* Only populated/sent to receivers with matching JWT scope — full trace_id chain, stack snippet, internal IDs */
}
}
}
Justification — three reasons:
error_code + retry_hint separate those clearly.human_message + error_code + retry_hint; the auditor with the right JWT scope sees diagnostic.* too. Cross-host the JWT-binding has to be host-aware; receivers without the scope filter out diagnostic before surfacing.Open question 5 resolution: Yes, the #1017 audit_envelope hash strategy carries over — the error envelope is the read-surface; the audit envelope is the write-surface with same JWT discipline. Confirmed.
Decision: schema_version follows MAJOR.MINOR.PATCH SemVer convention with per-axis producer/consumer rules:
| Axis | Producer must | Consumer must |
|---|---|---|
| MAJOR | Bump on breaking changes (field removal, type change, required→optional flip on input side) | Reject same-MAJOR mismatch with ENVELOPE_MALFORMED error envelope |
| MINOR | Bump on additive changes (new optional fields, new enum values where unknown→default semantics hold) | Accept ANY same-MAJOR version; unknown fields outside extensions.* log a warning but do NOT break |
| PATCH | Bump on bug fixes (no schema change) | Accept silently |
extensions.* |
Add freely under namespace; never break compat | Silently ignore unknown namespaces |
Justification — methodology-32 Postel discipline applied:
extensions.* are silently ignored; unknown fields outside extensions.* produce warnings (Pattern-073-style drift signal) but the receiver doesn’t crashTrade-off acknowledged: Schema-version coordination across plugin deploys creates a small operational cost (the plugin’s config must declare format_versions_emitted + format_versions_accepted; doc-sync-sweep catches drift). This is captured under §Consequences/Negative.
config; source-of-truth is the schema spec fileDecision: The plugin (config + CLAUDE.md + skills + MCP server per PM’s 2026-06-01 clarification) carries the context-package format declaration in config, but the source-of-truth is a separate schema spec file referenced by both config and the MCP server implementation.
# plugin/config (excerpt)
context_package_format:
spec: "schemas/context-package-1.0.0.json" # source of truth
versions_emitted: ["1.0.0"]
versions_accepted: ["1.0.0", "0.9.x"] # backward compat range
extensions_namespace: "vendor.piper-morgan"
<!-- plugin/CLAUDE.md (excerpt) -->
## Context Package Format
This plugin emits and accepts context packages per ADR-065
(`docs/internal/architecture/adrs/adr-065-canonical-context-package-format.md`).
The canonical schema is at `plugin/schemas/context-package-1.0.0.json`.
See ADR-065 §Decision D2 for envelope/body/extensions structure.
# plugin/mcp_server/serializer.py (excerpt)
SCHEMA_SPEC_PATH = "schemas/context-package-1.0.0.json" # MUST match config
Justification — Pattern-073 drift discipline:
config declares the version; MCP server implements against it).config claims version 1.0.0 but MCP server is built against 0.9.x — same as the documentation-asserted-behavior pattern that surfaced 9+ times in Pattern-073.CLAUDE.md is human-facing; it doesn’t carry version strings (that would be a third drift point). It points at the schema spec file by path.skills reference the format by name when they emit/consume packages (e.g., a skill that emits an audit_event package); they don’t carry version strings either.Open question 3 resolution: spec file is source of truth; config declares versions; MCP server implements; CLAUDE.md describes by reference; skills reference by name. Doc-sync-sweep catches drift. Confirmed.
envelope.package_type (D2) routes to the right body schema.extensions.* namespace (D2) lets the format evolve through additive changes without breaking deployed receivers. Producers are conservative (every change earns the right SemVer axis bump); consumers are liberal (unknown extensions silently ignored).diagnostic.* visibility. audit_event package_type’s body shape IS the ADR-063 envelope (D2 composition note).surface_type slot shape (D3) prevents the verb-object name collapsing that #1158 surfaced in the action-classifier. Same architectural shape resolves the same shape of bug at the BYOC boundary; the layer-then-migrate ruling (2026-06-06 ADR-060 amendment) inherits naturally if BYOC ever absorbs an existing capability registry.config and MCP server both reference; doc-sync-sweep catches drift” is the same disciplined-pattern that surfaced as Pattern-073 9+ times. Doc-asserted-behavior drift is prevented by one-source-of-truth + sync-sweep at the packaging layer, not at runtime.config must declare format_versions_emitted + format_versions_accepted accurately; MCP server must implement against the schema spec file accurately; CLAUDE.md must point at the right spec file. Doc-sync-sweep (Pattern-073 discipline) is the mitigation, but it’s a discipline cost not zero overhead.claim: available | conditionally_available | unavailable puts evaluation work on the receiver. This is the correct semantic (EC-2 ruling) but adds receiver-side complexity vs. a simple boolean claim. Receivers must implement conditions predicate evaluation; SDK helpers will mitigate (Q7 ADR-066 packaging-layer abstraction).context-package-1.0.0.json schema file — that’s a follow-up artifact (Q1 open question); this ADR specifies the structure (D1-D6) the schema file must encode(Empty at v0.1 filing. Klatch-pause framing per Pattern-064 convention: when Klatch resumes and Daedalus relays refinements via Janus, fold into this section as dated entry.)
context-package-1.0.0.json schema file to be drafted as a follow-up artifact; this ADR specifies the structure (D1-D6); Lead Dev review at schema draft.config declares versions; MCP server implements against the spec; CLAUDE.md describes by reference; skills reference by name. Doc-sync-sweep catches drift (Pattern-073 layer).diagnostic.* from human_message + error_code + retry_hint.