# Agent Blueprint Schema — Layer 3 Domain Entity Type # KNO Schema Version: 0.3.0 # # An Agent Blueprint is a declarative manifest that composes a deployable # agent persona from PlatformCapabilities, Blueprints, conduits, and # persona-runtime fields. It is the source-of-truth for personas; the # agent-card and `/.well-known/agent.json` are derived projections (DD-A2A-01 # Path X — see Decision D2 in the spike). # # If a PlatformCapability is a finished LEGO model and a Blueprint is the # instruction manual that snaps Capabilities together, an Agent Blueprint # is the *operator manual* for a persona that USES those assembled systems: # what it sees, what it's trying to achieve, what it must not do, which # channels it operates through, and what Charter authorises its scope. # # EXTENDS: document-schema.kno (which composes identity, history, quality) # MAPS TO: agent-card-schema.kno (A2A Protocol Specification § 5.5 AgentCard) # via DD-A2A-01 Path X — the agent-blueprint is the source-of-truth # and `content/agents/.kno` (service-config envelope) is # replaced for personas. The agent-card → /.well-known/agent.json # chain becomes a single P10 thin transformation FROM this entity. # Innovates beyond: A2A AgentCard by adding (a) PlatformCapability and # Blueprint composition (P13), (b) the conduit primitive that # binds capability access to substrate tiers and audit dimensions, # (c) Charter binding for scope-monotonicity, and (d) persona- # runtime fields (perception, goals, boundaries, spawn-policy, # tool-scopes, data-scopes, safety-level). A2A AgentCard alone # describes "who I am and what I expose"; an agent-blueprint # describes "what I am authorised to BECOME and DO." See # .github/instructions/open-standards-stewardship.instructions.md. # # RELATIONSHIP TO EXISTING SCHEMAS: # - platform-capability-schema.kno: The atoms an agent-blueprint composes. # References PlatformCapabilities via `composes.capabilities[].ref` # (sense (b) of "capability" — see DD-AB-03 vocabulary disambiguation). # - blueprint-schema.kno: Build-manuals. An agent-blueprint MAY reference # Blueprints via `composes.blueprints[]` to express dependencies on # assembled systems. Build-manual semantics stay in blueprint-schema; # persona-runtime semantics stay here. Sibling primitives, not subtypes. # - capability-schema.kno: PermissionTuple shape (sense (a)). Tuples are # declared INLINE under `persona.permission_tuples[]`, mirroring the # existing convention in role-schema.kno. Never appears under # `composes.capabilities[]`. # - agent-card-schema.kno: The A2A projection target. agent-blueprint # SUPERSEDES the `service-config@0.3.0 + subtype: agent-card` envelope # pattern for personas (Path X migration). Non-persona service-configs # keep the envelope. # - role-schema.kno: Actor definitions. Roles describe responsibilities # and autonomy for human/platform/system actors. Agent-blueprints # describe agent-runtime concerns (perception, conduits, tool_scopes, # model_role, spawn_policy). Sibling primitives — an agent-blueprint # MAY reference a role via `persona.acts_as_role` for organisational # context. # - perception-domain-schema.kno: Slugs referenced from # `persona.perception.domains[]` MUST resolve to a # `content/perception-domains/*.kno` entity. Drift-guard test enforces. # - process-template-schema.kno: The 6-phase loop a persona instantiates. # Referenced via `persona.process_template_xri` (default: # `pspace://process-template/agent-loop`). # # THREE-GATE TEST (validated in # research/2026_05_10-blueprint-cedar-preceptor-spike/02-persona-composition.md # § 2; revalidated 2026-05-10 at schema authoring time): # Gate 1 (Distinctness): YES — PlatformCapability composition + persona- # runtime fields + conduit binding + Charter scope-monotonicity is a # structurally distinct shape from build-manual assembly # (blueprint-schema) and responsibility/autonomy declaration # (role-schema). Shape A (extend Blueprint) and Shape C (extend Role) # both fail Gate 1 + Gate 3 per the spike's verdict table. # Gate 2 (Reusability): YES — 6 existing personas in content/agents/ # migrate under Path X (echo-agent, hindsight-reviewer, # integration-schema-analyzer, design-reviewer-v3, capability-provisioner, # integration-quickstart), with 13 M22 personas (A1-A13) and an open # long tail beyond. # Gate 3 (Clarity): YES — keeps each sibling primitive coherent. # blueprint-schema describes WHAT to build; agent-blueprint-schema # describes WHO USES IT and UNDER WHAT AUTHORITY. The capability # vocabulary disambiguation (DD-AB-03) is enforced here, eliminating # the three-way collision per file. # # DESIGN DECISIONS: # DD-AB-01: Agent-blueprint is the source-of-truth for personas; the # agent-card and /.well-known/agent.json are derived # projections (DD-A2A-01 Path X). Spike § 4. # DD-AB-02: Sibling primitive to blueprint-schema and role-schema, not a # subtype of either (Three-Gate verdict above; spike § 2). # DD-AB-03: Capability vocabulary disambiguation enforced at the schema # level. PermissionTuple (sense (a)) is INLINE under # `persona.permission_tuples[]`. PlatformCapability (sense (b)) # is referenced via XRI under `composes.capabilities[]`. # A2AFeature (sense (c)) is declared ONCE under # `a2a_projection.features` and never under `composes.*`. # Validator rejects PlatformCapability XRIs under # permission_tuples and PermissionTuple objects under # composes.capabilities. Spike § 5. # DD-AB-04: `composes.blueprints[].relation` explicitly distinguishes # `installed_by`, `depends_on_running`, and `acts_within` so # the Preceptor has a clear gate at precept(). Spike § 6. # DD-AB-05: Conduits are INLINE in `persona.conduits` rather than a # standalone schema. Standalone fails Three-Gate Gate 1 + 3 # (a conduit's reason-to-exist is to bind a PlatformCapability # to a tier within a persona; it does not exist outside a # persona). Spike § 5 (03-conduit-primitive.md). The four # conduit kinds — `ingress`, `egress`, `spawn`, # `platform-internal` — are declared inline under # `persona.conduits` per the normative SCHEMA DEFINITION # below. v0.2.0 lands the field-by-field shape per spike § 3 # (#2607); v0.1.0 reserved the slot. YAML key for the # platform-internal kind is `platform_internal` (underscore # form); the audit_dimension prefix uses the hyphen form # (`platform-internal.`). # DD-AB-06: Charter binding is a required block when `safety_level >= L1`. # `charter.authored_by` references a decision entity that # ratified the persona's scope; `scope_monotonicity: enforced` # means any scope-widening requires a new agent-blueprint # version AND a new decision entity. Spike § 3 + § 4 # (04-cedar-at-preceptor.md). # DD-AB-07: `process_template_xri` defaults to the canonical 6-phase # agent-loop (`pspace://process-template/agent-loop`). Per- # phase overrides (max_passes, quality_threshold, AECS # thresholds) live on the agent-blueprint, not on the # template (the template stays the singleton). # DD-AB-08: `lifecycle: bounded | continuous` is declared per-persona # (the agent-loop template's default is `bounded`; A6 / A13 # override to `continuous`). Resolves the deferred decision # in `content/process-templates/agent-loop.kno` header. # DD-AB-09: visibility:public is the collection default per REQ-18. # agent-blueprint entities are public reference knowledge by # default — they describe Possibility-discoverable agents and # are consumed via the four-surface contract. Individual # entities MAY override with their own `visibility:` field # (last-write-wins per REQ-18). The `agent-blueprint` # collection MUST be added to PUBLIC_COLLECTIONS in # services/pspace-api/src/lib/public-collections.ts and its # mirror in services/pspace-site/src/lib/public-collections.ts # before any visibility:public instance ships. Spike § 4.2 AC. # DD-AB-10: Manifest location is `content/agent-blueprints/.kno`. # Existing `content/agents/.kno` files migrate under # Path X (M56 work, #2613). Until migration, the two # collections coexist; the routed-collection-cascade lint # enforces no slug collisions across them during the # transition. # DD-AB-11: Trust-tier binding (P11). `persona.safety_level: L0..L3` is # the trust-tier selector input the Preceptor consumes at its # `precept()` gate per `docs/architecture/bedrock/kno-foundational-principles.md` # § "P13 in P11 — The Preceptor `precept()` gate". The # one-to-one mapping is L0→T0 (telemetry-only), L1→T1 # (low-risk effects, charter-bound), L2→T2 (substrate-write # effects, charter-bound + audit), L3→T3 (full Preceptor-gated # execution, charter-required + audit + scope-monotonicity). # Static-analysis counterparts (validator rules AB-001..010 in # `scripts/validate-kno.ts`; AB-006..010 cover the conduit # primitive landed in v0.2.0 per #2607) catch the cases that # would always fail `precept()`. Spike § 3 + § 4. # # AUTHORING WARNING — visibility:public foot-gun (REQ-18): # Per DD-AB-09 the collection default is `visibility:public`, and the # `agent-blueprints` row in `content/registries/public-collections.kno` # already carries the `private_rationale` deferring the routed surface # to #2202. Until #2202 lands and the four-surface projection (REST + # llms.txt + MCP + A2A) is in place, any agent-blueprint instance that # sets or inherits `visibility:public` will fail # `scripts/lint-public-surface-parity.ts --strict` (pre-commit + CI). # In the interim, instance authors MUST either: (a) set # `visibility: private` explicitly on the instance, or (b) leave the # collection-level `private_rationale` in place so the lint suppresses # parity findings. Both forms are valid; #2202 will retire option (b). # ============================================================================= # SCHEMA DECLARATION (RFC-007) # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # IDENTITY (Layer 1) # ============================================================================= id: 01KRAJXCVCTH7YDWWEZ5V210QG slug: agent-blueprint-schema type: spec version: 0.3.0 # ============================================================================= # VISIBILITY DECLARATION (REQ-18) — collection default # ============================================================================= # Agent-blueprint entities (content/agent-blueprints/*.kno) are public reference # knowledge by default — they describe Possibility-discoverable agent personas # and are consumed by the A2A surface, the MCP surface (collection enumeration), # and the REST API. Per REQ-18, individual entities MAY override with their # own `visibility:` field (last-write-wins at the entity level). Drives the # four-surface contract per kno-system_architecture.md § Agent Surface # Integration and public-surface-parity.instructions.md. See DD-AB-09 for # the PUBLIC_COLLECTIONS registration requirement. visibility: public # ============================================================================= # SCHEMA DEFINITION — persona.conduits (v0.2.0, #2607) # ============================================================================= # Normative field-by-field shape for the conduit primitive. Conduits are # inline under `persona.conduits` (DD-AB-05). Enforcement lives in # `scripts/validate-kno.ts` `validateAgentBlueprint()` rules AB-006..010. # # Four conduit kinds (closed set, AC2): # # ingress — persona ← world (e.g. perception-domain reads) # egress — persona → world (e.g. T1/T2/T3 writes) # spawn — persona → child agent (delegation) # platform-internal — persona ↔ platform-internal route (#1670 / #2202) # # YAML container shape under `persona.conduits`: # # persona: # conduits: # ingress: [] # array of ingress conduit entries # egress: [] # array of egress conduit entries # spawn: {} # single object (one spawn policy per persona) # platform_internal: [] # array; YAML key uses underscore form # # All four keys are OPTIONAL. A persona MAY declare zero or more of any kind. # Validator rejects unknown keys under `persona.conduits` (AB-006). # # Per-entry shape by kind (AC1): # # ingress entry: # slug: string, required — Cedar Action identifier # capability_ref: XRI, required — kno://content/capabilities/ # or kno://specs/platform-capability-schema # tier: enum, required — T1 (AC4: ingress→T1) # perception_domain_ref: XRI, required — kno://content/perception-domains/ # or kno://specs/perception-domain-schema # filters: array, optional — parametric Cedar conditions # redaction_policy: XRI, optional — kno://content/policies/ # audit_dimension: string, required — MUST equal `ingress.` (AC3) # # egress entry: # slug: string, required # capability_ref: XRI, required # tier: enum, required — T1 | T2 | T3 (AC4) # proposes_to: XRI, optional — kno://content/decisions/; # required when tier == T3 # filters: array, optional # redaction_policy: XRI, optional # audit_dimension: string, required — MUST equal `egress.` (AC3) # # spawn (single object, not array): # allowed: array of XRIs, required — superset of delegable # delegable: array of XRIs, required — subset of allowed # (Amplifier A1: never wider) # max_depth: integer ≥1, required # max_fanout: integer ≥1, required # tier: enum, optional — T1 | T3 (AC4) # audit_dimension: string, required — MUST equal `spawn.` # (AC3; = the # agent-blueprint's slug) # # platform_internal entry: # slug: string, required # capability_ref: XRI, required # operations: array of strings, required — closed allow-list # (≥1, no wildcards) # tier: enum, required — T1 | platform-only (AC4) # preceptor_rule: XRI, required — kno://content/decisions/ # audit_dimension: string, required — MUST equal # `platform-internal.` # (AC3; hyphen prefix even though # YAML key uses underscore) # # Cedar Action mapping (AC5): # Each conduit `slug` projects 1:1 to a Cedar Action `Conduit::""` # (spike § 4). Validator rejects `slug` values that collide with the # reserved Cedar Action / keyword set (rule AB-010). See # `scripts/validate-kno.ts` for the canonical reserved-name list and the # growth process. # # Tier-binding matrix (AC4, per spike § 6): # # | kind | allowed tier values | # |-------------------|----------------------------| # | ingress | T1 | # | egress | T1, T2, T3 | # | spawn | T1, T3 (optional) | # | platform-internal | T1, platform-only | # # Versioning (DD-AB-05, spike § 7): # Adding a conduit is non-breaking. Removing or narrowing a conduit is # safe (no widening). Widening `operations[]`, `filters[]`, `allowed[]`, # `delegable[]`, `max_depth`, or `max_fanout` is a Charter-scope- # monotonicity event and requires a new agent-blueprint version AND a new # decision entity (DD-AB-06). # ============================================================================= # ============================================================================= # SCHEMA DEFINITION — deployment (v0.3.0, #2030) # ============================================================================= # Optional top-level `deployment` block declaring WHERE this agent's loop is # allowed to run. Layer 3 vocabulary referenced via slugs that MUST resolve to # `content/environments/.kno` entries (open file-driven enum mirroring # the `perception-domain` pattern — DD-DEP-02). # # YAML shape: # # deployment: # environments: # optional array of environment slugs # - staging # - production # # Semantics (DD-DEP-03 — Default-allow): # - Block omitted entirely → agent is allowed in EVERY environment # (back-compat with v0.1.0/v0.2.0 # blueprints; no migration burden). # - Block present, environments # omitted or empty → SHAPE error (validator rule AB-013). # - Block present, environments # non-empty → agent is allowed ONLY in the listed # environments. PSPACE_ENV at runtime # must match one of these slugs (Phase 4 # runtime filter; Phase 7 deploy gate). # # Tenant-context exclusion (DD-DEP-07 — AB-014): # When `ownership.context: tenant`, an explicit `deployment.environments[]` # is REJECTED. Tenant agents inherit their tenant's environment from # provisioning; declaring scoping on the blueprint would conflict with # the platform-tenant separation model (platform-stewardship principle 1). # # Orthogonality to `persona.lifecycle` (DD-DEP-06): # `deployment.environments[]` declares WHERE the loop runs. # `persona.lifecycle` (#852) declares HOW the loop terminates (bounded | # continuous). Distinct concerns; neither subsumes the other. # # Three enforcement layers (DD-DEP-09): # 1. PR-time lint — `scripts/lint-agent-environment-declarations.ts` # (Phase 5) — catches typos and unresolved environment slugs. # 2. Runtime startup filter — `agents-by-environment.ts` (Phase 4) — emits # structured `agent_scoped_out` events for skipped agents. # 3. Deploy-time gate — `scripts/deploy-gate-agent-environments.sh` # (Phase 7) — fail-closed `deploy_target_excluded_by_blueprint` # error class per silent-failure-discipline Rule 8. # # Deferred to follow-ups: # - `deployment.cadence_overrides[]` — DD-DEP-05; distinct concern. # - `feature_flag: ` sibling — DD-DEP-08; distinct concern. # # Versioning: # Adding `deployment` is non-breaking. Removing it widens scope (back to # default-allow) and is a Charter-scope-monotonicity event when # `safety_level >= L1`. Adding more environments to the list widens scope # and is also a Charter event. Narrowing is safe. # ============================================================================= # ============================================================================= # STANDARD TIER # ============================================================================= title: "Agent Blueprint Schema" purpose: | Define the schema for Agent Blueprints — declarative manifests that compose a deployable agent persona from PlatformCapabilities, Blueprints, conduits, and persona-runtime fields. **What is an Agent Blueprint?** An Agent Blueprint is the **source-of-truth manifest** for a Possibility agent persona. Per DD-A2A-01 Path X (spike § 4), the agent-card and `/.well-known/agent.json` are *derived projections* of an agent-blueprint — there is exactly one source-of-truth file per persona and one P10 transformation step to the wire format. An agent-blueprint declares, in one entity: - **What the persona is composed of** — which PlatformCapabilities and Blueprints it depends on or installs (`composes.*`). - **What it perceives** — which perception domains feed it observations (`persona.perception.domains[]`). - **What it is trying to achieve** — measurable goals (`persona.goals[]`). - **What it must not do** — boundaries (`persona.boundaries[]`). - **Which tools and data it may touch** — `persona.tool_scopes[]` and `persona.data_scopes.{read,write,propose}`. - **Inline PermissionTuples** — sense-(a) capabilities (`persona.permission_tuples[]`). - **Which channels it operates through** — conduits binding capability access to substrate tiers (`persona.conduits.*`; detailed shape in #2607). - **Under what Charter authority** — `charter.authored_by` references the decision entity that ratified the persona's scope; scope-widening requires a new agent-blueprint version AND a new decision entity (`charter.scope_monotonicity: enforced`). - **How it loops** — `persona.process_template_xri` (default: the canonical 6-phase agent-loop) plus per-phase overrides. - **How it projects onto A2A** — `a2a_projection.*` declares the A2AFeatures (sense (c)) and projection metadata for the agent-card. **Vocabulary disambiguation (DD-AB-03):** The word "capability" historically carried three senses across schemas. In an agent-blueprint, each sense has exactly one home: | Sense | Where it appears in agent-blueprint | |-----------------------------|--------------------------------------------------------------------| | (a) PermissionTuple | INLINE under `persona.permission_tuples[]` | | (b) PlatformCapability | XRI reference under `composes.capabilities[]` | | (c) A2AFeature | Declared ONCE under `a2a_projection.features` | Validator rejects misplacements (XRIs under permission_tuples, tuples under composes.capabilities, features under composes.*). This is the schema-level enforcement of the disambiguation surfaced in spike § 1.4 and resolved in #2605. **Path X migration (DD-AB-01, DD-AB-10):** Existing agent personas under `content/agents/*.kno` use the `service-config@0.3.0 + subtype: agent-card` envelope. Under Path X (spike § 4), each persona migrates to `content/agent-blueprints/.kno`. The `service-config` envelope pattern is preserved for non-persona service configs; the migration is persona-scoped only and proceeds strangler-fig (per persona, observe-mode first) in M56 (#2613). v0.1.0 of this schema is the contract that adoption work consumes. **Derived Views (P10 Thin Transformations):** | Derived View | Source Fields | Endpoint | |-------------------------------|-----------------------------------------------------|-----------------------------------| | Agent Card (A2A § 5.5) | identity + a2a_projection + persona.{goals,boundaries,perception} | `/.well-known/agent.json` | | Cedar policy set | persona.permission_tuples + conduits + charter | (build-time, M56 #2610) | | Library listing | title + purpose + persona.goals + safety_level | Agent catalog API | | MCP collection enumeration | identity + persona.tool_scopes | Generic MCP collection server | | llms.txt entry | title + purpose | `/llms.txt` outline | **Deployment scoping (DD-DEP-01..09, v0.3.0, #2030):** An optional top-level `deployment` block declares WHERE the agent's loop is allowed to run. `deployment.environments[]` carries slugs that MUST resolve to `content/environments/.kno` registry entries. Omitting the block means default-allow (every environment); declaring it scopes the agent to the listed environments only. Tenant-context blueprints (`ownership.context: tenant`) MUST NOT declare `deployment.environments[]` — tenant agents inherit their tenant's environment from provisioning (DD-DEP-07; AB-014). Orthogonal to `persona.lifecycle` (#852): deployment declares WHERE the loop runs; lifecycle declares HOW it terminates (DD-DEP-06). Enforcement spans three layers — PR-time lint, runtime startup filter, deploy-time gate (DD-DEP-09; silent-failure-discipline Rule 8). See SCHEMA DEFINITION block above for the full shape. **Layer 3 Position:** Agent Blueprint extends document (Layer 2), which composes identity, history, and quality (Layer 1). # ============================================================================= # RICH TIER — Provenance & Taxonomy # ============================================================================= provenance: origin: id: 01KRAJXCVCTH7YDWWEZ5V210QG timestamp: "2026-05-10T00:00:00Z" tool: manual issue: "https://github.com/PossibilityTruthy/possibility-space/issues/2606" note: | Authored for M22-P3c #2606 ("Adopt agent-blueprint-schema as a sibling of capability-schema and blueprint-schema") per the AC list in research/2026_05_10-blueprint-cedar-preceptor-spike/06-decision.md § 4.2. The shape follows the sketch in research/2026_05_10-blueprint-cedar-preceptor-spike/02-persona-composition.md § 3 verbatim, with the conduit sub-shape deferred to #2607 per DD-AB-05. Three-Gate test revalidated at authoring time (see schema header). Shape B (sibling primitive) selected over Shape A (extend blueprint) and Shape C (extend role); Path X (replace service-config envelope for personas) selected over Path Y (compose alongside). Names "agent-blueprint" and "conduit" were ratified 2026-05-10 per #2608, ending the 7-day Naming-as-Discipline provisional window. Per the open-standards-stewardship reflex (.github/instructions/open-standards-stewardship.instructions.md), this schema's projection target is the A2A AgentCard (A2A Protocol Specification § 5.5); the additive Possibility-native blocks (composition, conduits, Charter binding, persona-runtime) are an Innovate move motivated by the gap A2A AgentCard does not address — "what authorises this persona to BECOME and DO." The agent-card itself remains a CONFORMS TO surface for A2A; the agent-blueprint sits above it. taxonomy: topics: - agent - persona - composition - charter - conduit - safety - a2a keywords: - agent-blueprint - persona - platform-capability - permission-tuple - a2a-feature - conduit - charter - scope-monotonicity - preceptor - cedar - process-template - perception-domain - safety-level # ============================================================================= # RICH TIER — Relationships # ============================================================================= relationships: extends: - xri: "kno://specs/document-schema" reason: "Layer 2 base type for all documents" depends_on: - xri: "kno://specs/kno-spec" reason: "Conforms to KNO format specification v0.0.9" - xri: "kno://specs/platform-capability-schema" reason: "Composes PlatformCapabilities via composes.capabilities[]" - xri: "kno://specs/perception-domain-schema" reason: "persona.perception.domains[] slugs MUST resolve to perception-domain entities" - xri: "kno://specs/process-template-schema" reason: "persona.process_template_xri references a process-template entity (default: agent-loop)" composes: - xri: "kno://specs/identity-schema" reason: "Layer 1: id, slug" - xri: "kno://specs/history-schema" reason: "Layer 1: _history, changelog" - xri: "kno://specs/quality-schema" reason: "Layer 1: quality, validation" related_to: - xri: "kno://specs/blueprint-schema" reason: "Sibling primitive. Build-manual semantics stay in blueprint-schema; agent-blueprint references Blueprints via composes.blueprints[] with an explicit relation (installed_by | depends_on_running | acts_within)." - xri: "kno://specs/role-schema" reason: "Sibling primitive. Roles describe responsibilities/autonomy; agent- blueprints describe agent-runtime concerns. persona.acts_as_role MAY reference a role for organisational context." - xri: "kno://specs/capability-schema" reason: "PermissionTuple shape (sense (a)). Tuples are declared inline under persona.permission_tuples[], mirroring role-schema's convention." - xri: "kno://specs/agent-card-schema" reason: "A2A projection target. agent-blueprint SUPERSEDES the service-config + subtype: agent-card envelope for personas under Path X (DD-A2A-01, DD-AB-01). Non-persona service-configs keep the envelope." - xri: "kno://content/process-templates/agent-loop" reason: "The canonical 6-phase loop (DISCOVER → ANALYZE → STRUCTURE → SHARE → ENACT → COMPLY) that personas instantiate by default." supersedes: - xri: "kno://content/agents/*" reason: "Path X (DD-AB-01, DD-AB-10) — personas under content/agents/ (the service-config + subtype: agent-card envelope) migrate to content/agent-blueprints/. Migration is strangler-fig in M56 (#2613). Non-persona service-configs are unaffected." enables: - xri: "kno://content/agent-blueprints/*" reason: "All Agent Blueprint instances conform to this schema" # ============================================================================= # RICH TIER — Quality # ============================================================================= quality: completeness: 0.9 last_reviewed: "2026-05-13" review_status: draft reviewed_by: "copilot" # ============================================================================= # HISTORY (P9 Temporal) # ============================================================================= _history: retention: full format: changelog changelog: - version: "0.3.0" date: "2026-05-13" author: "copilot" summary: "Optional deployment.environments[] block for env-scoping (Phase 3 of #2030)" changes: - "Added optional top-level `deployment` block per DD-DEP-01: a single block, not scattered fields, mirroring the one-block-per-concern convention of `composes`, `persona`, and `a2a_projection`." - "Default-allow semantics per DD-DEP-03: blueprints that omit the `deployment` block remain allowed in every environment (back-compat with v0.1.0 / v0.2.0; no migration burden on the 6 personas migrated under #2674)." - "Documented orthogonality to `persona.lifecycle` per DD-DEP-06: `deployment.environments[]` declares WHERE the loop runs; `lifecycle: bounded|continuous` (#852) declares HOW the loop terminates. Distinct concerns; neither subsumes the other." - "Validator rule AB-013 added: when `deployment` block is present, `environments[]` MUST be a non-empty array of strings (shape guard against the silent-no-op of an empty list)." - "Validator rule AB-014 added per DD-DEP-07: tenant-context blueprints (`ownership.context: tenant`) MUST NOT declare explicit `deployment.environments[]`; tenant agents inherit their tenant's environment from provisioning. Mixing the two would breach the platform-tenant separation model (platform-stewardship principle 1)." - "Slug-resolution lint deferred to Phase 5 (`scripts/lint-agent-environment-declarations.ts`) per DD-DEP-09 layer 1; runtime filter to Phase 4 (`agents-by-environment.ts`); deploy-time gate to Phase 7 (`scripts/deploy-gate-agent-environments.sh`, `deploy_target_excluded_by_blueprint` error class per silent-failure-discipline Rule 8)." - "Deferred to follow-ups (DD-DEP-05, DD-DEP-08): `deployment.cadence_overrides[]` and `feature_flag` sibling field. Both are distinct concerns from env scoping." - "MINOR bump (0.2.0 → 0.3.0): additive optional block; no breaking changes for existing instances. Per DD-DEP-03 every v0.2.0 instance remains valid as-is under v0.3.0." - version: "0.2.0" date: "2026-05-11" author: "copilot" summary: "Conduit primitive field-by-field shape (#2607)" changes: - "Landed normative SCHEMA DEFINITION block for `persona.conduits` per research/2026_05_10-blueprint-cedar-preceptor-spike/03-conduit-primitive.md § 3, retiring the v0.1.0 reservation slot (DD-AB-05)." - "Enumerated and validated four conduit kinds: `ingress`, `egress`, `spawn`, `platform-internal` (AC2)." - "Audit-dimension convention `.` enforced at validation time (AC3; ratified per #2636 and #2608 Naming-as-Discipline)." - "Tier-binding matrix enforced per spike § 6 (AC4): ingress→T1, egress→T1|T2|T3, spawn→T1|T3, platform-internal→T1|platform-only." - 'Cedar Action 1:1 mapping per spike § 4: `slug` → Cedar Action `Conduit::""`. Reserved-name collision check (AC5) implemented in validator rule AB-010.' - "Validator rules AB-006..AB-010 added to `scripts/validate-kno.ts` `validateAgentBlueprint()` (AC6 unit tests live at `scripts/__tests__/validate-kno-agent-blueprint-conduits.test.ts`)." - "MINOR bump (0.1.0 → 0.2.0): additive normative constraints; no breaking shape changes to v0.1.0 callers (no instances shipped at v0.1.0 — agent-blueprint adoption begins under M56 #2613)." - version: "0.1.0" date: "2026-05-10" author: "copilot" summary: "Initial Agent Blueprint schema for M22-P3c (#2606)" changes: - "Adopted as a sibling primitive to blueprint-schema and role-schema per the Three-Gate verdict in research/2026_05_10-blueprint-cedar-preceptor-spike/02-persona-composition.md § 2 (revalidated 2026-05-10)." - "Implements Path X (DD-A2A-01): agent-blueprint becomes the source-of- truth for personas; the agent-card and /.well-known/agent.json are derived projections (one P10 transformation step). Spike § 4." - "Capability vocabulary disambiguation (DD-AB-03) enforced at the schema level: PermissionTuple inline, PlatformCapability via XRI under composes.capabilities[], A2AFeature ONCE under a2a_projection.features. Validator rejects misplacements. Resolves the three-way collision in collaboration with #2605." - "Conduit sub-shape (DD-AB-05): the four kinds (ingress, egress, spawn, platform-internal) are enumerated and the slot is reserved under persona.conduits, but the field-by-field shape is owned by #2607 per spike § 03 § 3 to keep this issue's scope focused on composition + Charter + projection." - "Charter binding (DD-AB-06): required when safety_level >= L1. scope_monotonicity: enforced means any scope-widening requires a new agent-blueprint version AND a new decision entity." - "Process-template binding (DD-AB-07, DD-AB-08): defaults to the canonical 6-phase agent-loop; lifecycle (bounded | continuous) is declared per-persona, resolving the deferred decision in content/process-templates/agent-loop.kno." - "visibility:public collection default (DD-AB-09) per REQ-18. PUBLIC_COLLECTIONS registration in services/pspace-api/src/lib/ public-collections.ts and its mirror MUST land before any visibility:public instance ships." - "Manifest location is content/agent-blueprints/.kno (DD-AB-10); coexistence with content/agents/ during M56 migration is enforced via routed-collection-cascade lint (no slug collisions across the two collections)." - "Status: Experimental. Stabilises once the first persona instance (under #2613) round-trip projects to an A2A-conformant agent-card." - "Names 'agent-blueprint' and 'conduit' ratified 2026-05-10 per #2608 (7-day Naming-as-Discipline window closed)." - "Open-standards stewardship: this schema's projection target (agent-card) CONFORMS TO A2A AgentCard (A2A § 5.5); the additive Possibility-native blocks (composition, conduits, Charter, persona- runtime) are an Innovate move motivated by the gap A2A AgentCard does not address. See .github/instructions/open-standards-stewardship.instructions.md." recent: - version: 3 created: "2026-05-10T00:00:00Z" created_by: "copilot" modified: "2026-05-13T00:00:00Z" modified_by: "copilot" - version: 2 created: "2026-05-10T00:00:00Z" created_by: "copilot" modified: "2026-05-11T00:00:00Z" modified_by: "copilot" - version: 1 created: "2026-05-10T00:00:00Z" created_by: "copilot" modified: "2026-05-10T00:00:00Z" modified_by: "copilot"