@unified-product-graph/core 0.9.11 → 0.9.13

package/CHANGELOG.md

@@ -7,6 +7,45 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.9.13] - 2026-06-11
+
+**Foundations follow-ups: a registry-edge authoring path, specification stewardship, and three portfolio-scoped anti-patterns.** The deferred half of the foundations work (0.9.12) lands: canonical entities can now relate to one another in the registry, a specification can name its steward, and the registry surfaces the ways a foundations tier goes wrong across a portfolio.
+
+### Added
+- **`create_registry_edge`** (tools 119 to 120, local only): the authoring path for canonical-internal edges between registry entities, activating the reserved `registry.edges`. A registry `specification` can now be `governed_by` a registry `organization`, a `primitive` `defined_by` a `specification`, a `specification` extend another, all without touching a product graph. Validates that both endpoints exist in the registry, the type is a real catalogue edge, and the catalogue source and target types match the pair. Idempotent.
+- **`specification_governed_by_organization`** catalogue edge (edge count 979 to 980): a registry specification's stewardship, an organization as its governing body. Organizations are registry-hostable canonicals (`define_canonical_entity` already accepts the type), so the steward is a first-class entity, not a free-text field.
+- **Three portfolio-scoped anti-patterns** (`scope: 'portfolio'`, evaluated by `portfolio_validate`, surfaced in a new `portfolio_anti_patterns` block): `specification-without-implementer` (a registry specification no product, feature, or api_contract implements or conforms to), `primitive-scattered-without-canonical` (the same primitive title appears as a product-local node in two or more products with no registry canonical unifying them), and `product-reimplements-specification` (two or more products independently implement the same registry specification). These read the registry plus cross-product edges, context a single graph cannot express.
+
+### Changed
+- **`UPGCuratedAntiPattern` gains an optional `scope`** (`'graph'` default, or `'portfolio'`), and `structured_condition` is now optional. The single-graph evaluator skips portfolio-scoped patterns, so a portfolio pattern can never flip one product graph invalid; their detectors live in `portfolio_validate` instead. Anti-pattern count 15 to 18.
+
+No entity, domain, region, or playbook count change (entities 315, domains 37, regions 11, playbooks 13).
+
+---
+
+## [0.9.12] - 2026-06-10
+
+**Foundations: a first-class `specification` and `primitive` entity, plus a technical-domain enum widening.** Two governance moats that product orgs usually mismodel as products or scatter across features now have a home, and four engineering enums that real authoring outgrew are widened.
+
+### Added
+- **`specification` and `primitive` entity types** (entity count 313 to 315) in a new **`foundations`** domain and region. A `specification` is a governed spec a product implements, exposes, or conforms to (a query language, protocol, data format, encoding); a `primitive` is the compositional unit a specification defines (a block, a reference, a query value). Both are registry-hostable canonicals (`define_canonical_entity` accepts them), so a spec scattered across N products becomes one canonical that product instances link to via `instance_of`. `specification` carries a lifecycle (draft, active, deprecated, superseded); `primitive` is lifecycle-free. Both ship at `proposed` maturity, with a canonical playbook and a domain guide.
+- **11 foundations edges.** Four registry-internal catalogue edges: `specification_extends_specification` (a dialect or superset), `specification_competes_with_specification`, `primitive_defined_by_specification`, `primitive_composes_primitive`. Seven portfolio cross-edges from a product-graph entity to a registry canonical (the `instance_of` shape): `product_implements_specification`, `product_exposes_specification`, `feature_conforms_to_specification`, `api_contract_speaks_specification`, `product_exposes_primitive`, `feature_manipulates_primitive`, `primitive_stored_as_data_type`.
+- **`data_flow.orientation`** (`inbound`, `outbound`, `internal`): a separate axis from `direction` (cardinality), so a flow can be one-way and inbound at once.
+- **A `remap_property_value` migration kind** that remaps a properties-bag enum value in place, optionally splitting it into a sibling property.
+
+### Changed
+- **Four engineering enums widened** to fit real authoring: `service.service_type` gains `cli`; `api_contract.protocol` gains `SSE`; `integration_pattern.pattern_type` gains `adapter`, `client_library`, `host_embedding`, `pipes_and_filters`, `data_sync`.
+
+### Migrations (`UPG_PROPERTY_MIGRATIONS['0.9.12']`, dual-read on load)
+- `data_flow.direction` values `inbound` / `outbound` / `internal` move to the new `orientation` property; `direction` resets to `unidirectional`.
+- `integration_pattern.pattern_type`: `"data sync"` to `data_sync`, `backend_client` to `client_library`.
+- `service.service_type`: `backend` to `api`.
+- `api_contract.protocol`: `HTTP` to `REST`, `HTTP/SSE` to `SSE`.
+
+Edge-catalogue count 975 to 979; region count 10 to 11; domain count 36 to 37. No new tools (119).
+
+---
+
 ## [0.9.11] - 2026-06-10
 
 **Tooling DX (batch 6, part 2): status pre-flight + anti-pattern visibility.** Two discoverability fixes from the same real portfolio session, plus a self-trip fix.

package/dist/index.cjs

@@ -28,6 +28,7 @@ __export(index_exports, {
   DISCOVERY_RESEARCH_VALIDATION_PLAYBOOK: () => DISCOVERY_RESEARCH_VALIDATION_PLAYBOOK,
   ENGINEERING_PLATFORM_PLAYBOOK: () => ENGINEERING_PLATFORM_PLAYBOOK,
   EXPERIENCE_DESIGN_BRAND_PLAYBOOK: () => EXPERIENCE_DESIGN_BRAND_PLAYBOOK,
+  FOUNDATIONS_PLAYBOOK: () => FOUNDATIONS_PLAYBOOK,
   LEGACY_PRODUCT_STAGES: () => LEGACY_PRODUCT_STAGES,
   MARKDOWN_FORMAT_VERSION: () => MARKDOWN_FORMAT_VERSION,
   MARKET_COMPETITIVE_PLAYBOOK: () => MARKET_COMPETITIVE_PLAYBOOK,
@@ -683,6 +684,12 @@ var UPG_DOMAINS = [
     label: "Workspace",
     description: "Spatial thinking spaces for arranging entities, debating decisions, and committing to the graph. Workspaces are transient canvases that sit alongside all other domains, letting you compose and explore relationships before they become permanent graph structure. A framework exercise is a structured workspace: one run of a framework (MoSCoW, RICE, Kano, \u2026) applied to a chosen set of entities, with each entity's result recorded on the exercise-to-entity edge rather than the entity itself.",
     types: ["workspace", "framework_exercise"]
+  },
+  {
+    id: "foundations",
+    label: "Foundations",
+    description: "The shared specifications and foundational primitives a product organisation stewards or implements everywhere. Specifications are governed specs (query languages, protocols, data formats, encodings) like GROQ or Portable Text; primitives are the compositional units those specs define (a block, a reference, a query value). Both are registry-hostable canonicals that products implement, expose, or conform to. Distinct from a product feature: a specification has no single owner, no P&L, and no buyer; it is the rulebook many products point at.",
+    types: ["specification", "primitive"]
   }
 ];
 var UPG_ENTITY_TO_DOMAIN = Object.freeze(
@@ -702,6 +709,9 @@ function getDomainIdForType(entityType) {
 
 // src/registry/entity-meta.ts
 var UPG_ENTITY_META = [
+  // Foundations (0.9.12): shared specifications + the primitives they define.
+  { name: "specification", type_id: "ent_352", maturity: "proposed", since: "0.9.12" },
+  { name: "primitive", type_id: "ent_353", maturity: "proposed", since: "0.9.12" },
   // ── Strategic ──
   { name: "product", type_id: "ent_001", maturity: "stable", since: "0.1.0" },
   { name: "outcome", type_id: "ent_002", maturity: "stable", since: "0.1.0" },
@@ -3120,7 +3130,16 @@ var UPG_EDGE_CATALOG = {
   data_quality_rule_governs_data_source: { forward_verb: "governs", reverse_verb: "governed_by", classification: "semantic", source_type: "data_quality_rule", target_type: "data_source" },
   // press_release → launch (marketing → go_to_market). A press release had 0
   // outbound; it could not name the launch it announces.
-  press_release_announces_launch: { forward_verb: "announces", reverse_verb: "announced_by", classification: "cross-domain", source_type: "press_release", target_type: "launch" }
+  press_release_announces_launch: { forward_verb: "announces", reverse_verb: "announced_by", classification: "cross-domain", source_type: "press_release", target_type: "launch" },
+  // ── Foundations (0.9.12): registry-internal relationships between canonical
+  //    specifications and primitives. Product-to-foundation links (implements,
+  //    exposes, conforms_to) are portfolio cross-edges, not catalog edges.
+  specification_extends_specification: { forward_verb: "extends", reverse_verb: "extended_by", classification: "hierarchy", source_type: "specification", target_type: "specification" },
+  specification_competes_with_specification: { forward_verb: "competes_with", reverse_verb: "competes_with", classification: "semantic", source_type: "specification", target_type: "specification" },
+  primitive_defined_by_specification: { forward_verb: "defined_by", reverse_verb: "defines", classification: "semantic", source_type: "primitive", target_type: "specification" },
+  primitive_composes_primitive: { forward_verb: "composes", reverse_verb: "composed_by", classification: "hierarchy", source_type: "primitive", target_type: "primitive" },
+  // Stewardship: a registry specification is governed by a (registry-hostable) organization (0.9.13).
+  specification_governed_by_organization: { forward_verb: "governed_by", reverse_verb: "governs", classification: "semantic", source_type: "specification", target_type: "organization" }
 };
 var UPG_POLYMORPHIC_EDGE_KEYS = [
   // Universal semantic verbs
@@ -3187,7 +3206,14 @@ var UPG_CROSS_EDGE_TYPES = [
   "instance_of",
   "area_serves_persona",
   "area_targets_market_segment",
-  "rolls_up_to"
+  "rolls_up_to",
+  "product_implements_specification",
+  "product_exposes_specification",
+  "feature_conforms_to_specification",
+  "api_contract_speaks_specification",
+  "product_exposes_primitive",
+  "feature_manipulates_primitive",
+  "primitive_stored_as_data_type"
 ];
 var REGISTRY_PRODUCT_ID = "registry";
 
@@ -3251,6 +3277,13 @@ function resolveEntityType(rawType) {
 
 // src/grammar/hierarchy.ts
 var UPG_VALID_CHILDREN = {
+  // ── Foundations (0.9.12): registry canonicals that self-nest. A
+  //    specification extends a specification (a dialect of a parent spec); a
+  //    primitive composes primitives (a block contains spans). These back the
+  //    hierarchy-classified specification_extends_specification /
+  //    primitive_composes_primitive catalog edges.
+  specification: ["specification"],
+  primitive: ["primitive"],
   // ── Product (root) ─────────────────────────────────────────────────────────
   product: [
     // Strategy
@@ -6171,9 +6204,42 @@ var FRAMEWORK_EXERCISE_LIFECYCLE = {
     }
   ]
 };
+var SPECIFICATION_LIFECYCLE = {
+  entity_type: "specification",
+  initial_phase: "draft",
+  terminal_phases: ["superseded"],
+  phases: [
+    {
+      id: "draft",
+      label: "Draft",
+      description: "Being authored. Not yet adopted as the canonical specification.",
+      transitions_to: ["active", "superseded"]
+    },
+    {
+      id: "active",
+      label: "Active",
+      description: "In force. The current authoritative version products implement and conform to.",
+      transitions_to: ["deprecated", "superseded"]
+    },
+    {
+      id: "deprecated",
+      label: "Deprecated",
+      description: "Still valid but no longer recommended; a successor exists or is imminent.",
+      transitions_to: ["superseded"]
+    },
+    {
+      id: "superseded",
+      label: "Superseded",
+      description: "Replaced by a newer specification. Retained for historical reference.",
+      transitions_to: []
+    }
+  ]
+};
 var UPG_LIFECYCLES = [
   // Product (root)
   PRODUCT_LIFECYCLE,
+  // Foundations (0.9.12)
+  SPECIFICATION_LIFECYCLE,
   // Discovery & Validation
   RESEARCH_STUDY_LIFECYCLE,
   NEED_LIFECYCLE,
@@ -6281,6 +6347,9 @@ function getLifecycleForType(entityType) {
   return UPG_LIFECYCLES.find((l) => l.entity_type === entityType);
 }
 var UPG_LIFECYCLE_FREE_TYPES = /* @__PURE__ */ new Set([
+  // ── Foundations (1 of 2): a primitive either exists or is deprecated; no
+  //    phase ladder (like metric). `specification` carries a lifecycle. ──
+  "primitive",
   // ── User (5): personas and JTBD atoms are reference data ──────────────────
   "persona",
   "job",
@@ -7352,6 +7421,50 @@ function getDeprecatedTypes() {
   return deprecated;
 }
 var UPG_PROPERTY_MIGRATIONS = {
+  // ── v0.9.12: technical-domain enum widening + data_flow orientation split ──
+  //
+  // Real authoring outgrew four engineering-domain enums. 0.9.12 widens them
+  // (see properties/domains/engineering.ts) and adds a data_flow `orientation`
+  // axis distinct from `direction` (cardinality). These rules dual-read the
+  // legacy values so graphs authored before 0.9.12 stay valid on load:
+  //   - data_flow.direction inbound/outbound/internal -> properties.orientation,
+  //     and direction resets to unidirectional (all three were one-way).
+  //   - integration_pattern.pattern_type "data sync" -> data_sync,
+  //     backend_client -> client_library.
+  //   - service.service_type backend -> api (use the new `cli` for CLI tools).
+  //   - api_contract.protocol HTTP -> REST, HTTP/SSE -> the new SSE value.
+  "0.9.12": [
+    {
+      kind: "remap_property_value",
+      type: "data_flow",
+      property: "direction",
+      value_map: { inbound: "inbound", outbound: "outbound", internal: "internal" },
+      to_property: "orientation",
+      reset_value: "unidirectional",
+      reason: "data_flow.direction conflated cardinality with orientation; the orientation values move to the new `orientation` property and direction resets to `unidirectional` (0.9.12)."
+    },
+    {
+      kind: "remap_property_value",
+      type: "integration_pattern",
+      property: "pattern_type",
+      value_map: { "data sync": "data_sync", backend_client: "client_library" },
+      reason: 'integration_pattern.pattern_type widened in 0.9.12; legacy "data sync" snake-cases to data_sync and backend_client collapses to client_library.'
+    },
+    {
+      kind: "remap_property_value",
+      type: "service",
+      property: "service_type",
+      value_map: { backend: "api" },
+      reason: "service.service_type `backend` is too generic to canonise; normalised to `api` in 0.9.12 (use `cli` for command-line tools)."
+    },
+    {
+      kind: "remap_property_value",
+      type: "api_contract",
+      property: "protocol",
+      value_map: { HTTP: "REST", "HTTP/SSE": "SSE" },
+      reason: "api_contract.protocol normalised in 0.9.12: HTTP maps to REST and HTTP/SSE maps to the new SSE value."
+    }
+  ],
   // ── v0.8.0: UPG-574 deprecated-property removal pass ───────────────────
   //
   // The seven properties tagged `@deprecated since v0.4.0` that survived the
@@ -7845,6 +7958,25 @@ function migrateNodeProperties(node, fromVersion, toVersion) {
           }
           break;
         }
+        case "remap_property_value": {
+          const props = workingNode.properties;
+          if (!props || !(m.property in props)) break;
+          const oldValue = props[m.property];
+          if (typeof oldValue !== "string" || !(oldValue in m.value_map)) break;
+          const mapped = m.value_map[oldValue];
+          const nextProps = { ...props };
+          if (m.to_property) {
+            nextProps[m.to_property] = mapped;
+            nextProps[m.property] = m.reset_value ?? mapped;
+            changes.push({ kind: "remapped_property_value", property: m.property, to_property: m.to_property, value_changed: true });
+          } else {
+            nextProps[m.property] = mapped;
+            changes.push({ kind: "remapped_property_value", property: m.property, value_changed: mapped !== oldValue });
+          }
+          workingNode.properties = nextProps;
+          mutated = true;
+          break;
+        }
       }
     }
   }
@@ -9298,7 +9430,7 @@ var UPG_PROPERTY_SCHEMA = {
   // ApiContractProperties: API contract.
   api_contract: {
     spec_url: { type: "string", description: "URL of the specification document" },
-    protocol: { type: "string", enum: ["REST", "GraphQL", "gRPC", "AsyncAPI", "SOAP", "WebSocket", "MQTT", "other"], description: "Communication protocol" },
+    protocol: { type: "string", enum: ["REST", "GraphQL", "gRPC", "AsyncAPI", "SOAP", "WebSocket", "MQTT", "SSE", "other"], description: "Communication protocol. `SSE` (server-sent events) added in 0.9.12." },
     version: { type: "string", description: "API version" },
     owner: { type: "string", description: "Maintaining person or team." }
   },
@@ -9779,7 +9911,8 @@ var UPG_PROPERTY_SCHEMA = {
   data_flow: {
     trigger: { type: "string", description: "What triggers the flow" },
     data_type: { type: "string", description: "Type of data transferred" },
-    direction: { type: "string", enum: ["unidirectional", "bidirectional"], description: "Direction" },
+    direction: { type: "string", enum: ["unidirectional", "bidirectional"], description: "Direction (cardinality of the link)." },
+    orientation: { type: "string", enum: ["inbound", "outbound", "internal"], description: "Flow orientation relative to the system or component, a separate axis from `direction` (which is cardinality). A flow can be `unidirectional` AND `inbound`. Added in 0.9.12 to split the orientation axis that authors were conflating into `direction` (inbound/outbound/internal values)." },
     protocol: { type: "string", enum: ["rest", "graphql", "grpc", "event", "webhook", "file"], description: "Communication protocol" }
   },
   // DataLineageProperties: DataLineage entity.
@@ -10535,7 +10668,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // IntegrationPatternProperties: Integration pattern between systems.
   integration_pattern: {
-    pattern_type: { type: "string", enum: ["api", "event", "file", "database", "webhook"], description: "Type" },
+    pattern_type: { type: "string", enum: ["api", "event", "file", "database", "webhook", "adapter", "client_library", "host_embedding", "pipes_and_filters", "data_sync"], description: "Type. `adapter`, `client_library`, `host_embedding`, `pipes_and_filters`, `data_sync` added in 0.9.12." },
     protocol: { type: "string", description: "Communication protocol" }
   },
   // InteractionSpecProperties: Interaction specification.
@@ -11240,6 +11373,12 @@ var UPG_PROPERTY_SCHEMA = {
     tier_order: { type: "number", description: "Display ordering (1 = first tier shown)" },
     is_highlighted: { type: "boolean", description: "Highlighted as recommended / most popular" }
   },
+  // PrimitiveProperties: A foundational compositional unit a specification defines: the noun products
+  primitive: {
+    primitive_kind: { type: "string", enum: ["data_type", "object", "block", "unit"], description: "The shape of the thing products pass around." },
+    defined_by: { type: "string", description: "The `specification/<slug>` this primitive comes from; nullable for spec-less internal primitives. Mirrors the `primitive_defined_by_specification` edge for quick lookup." },
+    since: { type: "string", description: "Year or version the primitive was introduced." }
+  },
   // PrivacyPolicyProperties: Privacy policy.
   privacy_policy: {
     version: { type: "string", description: "Version identifier of the policy" },
@@ -11610,7 +11749,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // ServiceProperties: Service or microservice.
   service: {
-    service_type: { type: "string", enum: ["web", "api", "worker", "db", "queue", "library", "mobile", "docs", "lambda"], description: "Functional classification. Expanded from Backstage's component type vocabulary." },
+    service_type: { type: "string", enum: ["web", "api", "worker", "db", "queue", "library", "mobile", "docs", "lambda", "cli"], description: "Functional classification. Expanded from Backstage's component type vocabulary. `cli` added in 0.9.12." },
     tech_stack: { type: "string[]", description: 'Technologies used (e.g. ["TypeScript", "Postgres", "Redis"])' },
     owner: { type: "string", description: "Owning person or team. Backstage marks this required; strongly recommended." },
     lifecycle: { type: "string", enum: ["experimental", "production", "deprecated"], description: 'Service maturity. Answers "how mature is it?". `experimental` = early-stage. `production` = battle-tested. `deprecated` = being phased out.' },
@@ -11732,6 +11871,18 @@ var UPG_PROPERTY_SCHEMA = {
     },
     rice_score: { type: "number", description: "Computed: (reach \xD7 impact \xD7 confidence) / effort. @deprecated 0.9.0:computed by the `rice-scoring` framework on its application edge, not stored on the entity. Removed in 0.9.1." }
   },
+  // SpecificationProperties: A governed specification: a query language, protocol, data format, encoding,
+  specification: {
+    kind: { type: "string", enum: ["language", "protocol", "data_format", "encoding", "interface_contract", "object_model"], description: "What the artifact fundamentally is, independent of how it is governed." },
+    language_flavor: { type: "string", enum: ["query", "programming", "markup", "styling", "schema", "template"], description: "Set only when `kind` is `language`: the kind of language." },
+    governance: { type: "string", enum: ["open_spec_stewarded", "open_standard_consortium", "proprietary_open", "internal_primitive", "de_facto"], description: "How the specification is governed (its ratification status, and whether it counts as a `standard`). `open_standard_consortium` is a formal standard (W3C, IETF, ISO); `de_facto` and `internal_primitive` never became one." },
+    steward: { type: "string", description: "The governing body or organisation (may later become an `organization` ref)." },
+    openness: { type: "string", enum: ["open", "proprietary"], description: "Whether the specification itself is open or proprietary." },
+    spec_url: { type: "string", description: "URL of the published specification." },
+    current_version: { type: "string", description: "Latest published version string." },
+    since: { type: "string", description: "Year or version the specification was introduced." },
+    conformance: { type: "string", description: "How conformance is tested (test suite, certification program). Optional." }
+  },
   // StakeholderProperties: Stakeholder entity.
   stakeholder: {
     stakeholder_type: { type: "string", enum: ["internal", "external", "investor", "regulator"], description: "Relationship of the stakeholder to the organisation" },
@@ -19717,6 +19868,30 @@ var OPERATIONS_QUALITY_PLAYBOOK = {
     )
   ]
 };
+var FOUNDATIONS_PLAYBOOK = {
+  id: "playbook:foundations",
+  name: "Foundations",
+  version: "0.9.12",
+  description: "Register the specifications your products implement and expose, and the primitives those specs define, as canonical entities instead of scattered per-product features.",
+  region: "foundations",
+  is_canonical: true,
+  related_framework_ids: [],
+  target_anchor_entity: "specification",
+  creation_sequence: [
+    seqStep(
+      1,
+      "Specifications",
+      ["specification"],
+      "Define each governed spec your products implement, expose, or conform to (a query language, protocol, or format) as one canonical specification, not a per-product feature."
+    ),
+    seqStep(
+      2,
+      "Primitives",
+      ["primitive"],
+      "Define the compositional units those specs define (a block, a reference, a query value) as primitives, each linked to its specification."
+    )
+  ]
+};
 var UPG_PLAYBOOKS = [
   // Region 1 - strategy_outcomes
   STRATEGY_OUTCOMES_PLAYBOOK,
@@ -19739,7 +19914,9 @@ var UPG_PLAYBOOKS = [
   // Region 9 - analytics_data
   ANALYTICS_DATA_PLAYBOOK,
   // Region 10 - operations_quality
-  OPERATIONS_QUALITY_PLAYBOOK
+  OPERATIONS_QUALITY_PLAYBOOK,
+  // Region 11 - foundations
+  FOUNDATIONS_PLAYBOOK
 ];
 
 // src/step-sequence.ts
@@ -20481,7 +20658,7 @@ var UPG_DOMAIN_RINGS = [
     id: "build",
     label: "Build",
     description: "How do we construct it?",
-    domain_ids: ["engineering", "ai", "automation", "data_analytics", "testing", "devops", "security", "accessibility"]
+    domain_ids: ["engineering", "foundations", "ai", "automation", "data_analytics", "testing", "devops", "security", "accessibility"]
   },
   {
     id: "grow",
@@ -21396,10 +21573,30 @@ var WORKSPACE_GUIDE = {
     { description: "Workspace content is transient by default: promote discoveries to the graph, do not leave them in the workspace" }
   ]
 };
+var FOUNDATIONS_GUIDE = {
+  domain_id: "foundations",
+  anchor_entity: "specification",
+  creation_sequence: ["specification", "primitive"],
+  patterns: [
+    {
+      name: "Specification defines primitives",
+      description: "A specification governs one or more primitives; each primitive is defined_by the spec and may compose other primitives",
+      entity_types: ["specification", "primitive"],
+      edge_chain: ["primitive_defined_by_specification", "primitive_composes_primitive"]
+    }
+  ],
+  required_bridges: [],
+  anti_patterns: [
+    { description: "A specification scattered as duplicate features across products instead of one canonical with instance_of links" },
+    { description: "Modelling a governed spec as a product: it has no single owner, P&L, or buyer; it is the rulebook products point at" }
+  ]
+};
 var UPG_DOMAIN_GUIDES = [
   // Nucleus
   PORTFOLIO_GUIDE,
   WORKSPACE_GUIDE,
+  // Foundations (0.9.12)
+  FOUNDATIONS_GUIDE,
   // Ring 1: Understand
   USER_GUIDE,
   USER_RESEARCH_GUIDE,
@@ -24178,6 +24375,47 @@ var UPG_ANTI_PATTERNS = [
     stages: ["beta", "launch", "growth", "mature"],
     severity: "medium",
     source: { kind: "practitioner", attribution: "Marty Cagan, Inspired (product discovery)" }
+  },
+  // ── Foundations layer (0.9.13): portfolio-scoped, registry-aware ──────────
+  // These read the shared registry + cross-product edges, so they are evaluated
+  // by portfolio_validate, not the single-graph evaluator. They carry no
+  // structured_condition (the detector is cross-product, not a single-graph
+  // IntelligenceCondition).
+  {
+    id: "specification-without-implementer",
+    since: "0.9.13",
+    scope: "portfolio",
+    name: "Specification without implementer",
+    description: "A specification in the shared registry has no product, feature, or api_contract implementing or conforming to it anywhere in the portfolio. A specification nobody implements is a document, not a contract: it states an intent the portfolio never honours.",
+    why_it_matters: "An unimplemented specification carries authority it has not earned. Teams cite it as a standard while no surface actually conforms, so conformance claims cannot be trusted or traced.",
+    remediation: "Link at least one product, feature, or api_contract to the specification via `product_implements_specification`, `product_exposes_specification`, `feature_conforms_to_specification`, or `api_contract_speaks_specification`; or retire the specification from the registry.",
+    stages: ["validation", "build", "beta", "launch", "growth", "mature"],
+    severity: "medium",
+    source: { kind: "fundamental" }
+  },
+  {
+    id: "primitive-scattered-without-canonical",
+    since: "0.9.13",
+    scope: "portfolio",
+    name: "Primitive scattered without a canonical",
+    description: "The same primitive concept appears as a product-local node in two or more products, but no canonical primitive in the shared registry unifies them. Each product redefines the building block on its own terms, so the portfolio carries several drifting copies of one shared idea instead of a single authoritative definition.",
+    why_it_matters: "Scattered primitives drift apart in name, shape, and meaning. Cross-product reasoning breaks because the same concept reads as several unrelated entities, and a change to the shared building block has no single place to land.",
+    remediation: "Define the shared primitive once in the registry with `define_canonical_entity`, then link each product copy via `register_instance` so the building block has one authoritative definition.",
+    stages: ["build", "beta", "launch", "growth", "mature"],
+    severity: "medium",
+    source: { kind: "fundamental" }
+  },
+  {
+    id: "product-reimplements-specification",
+    since: "0.9.13",
+    scope: "portfolio",
+    name: "Specification reimplemented across products",
+    description: "Two or more products independently implement the same registry specification rather than one depending on a shared implementation. Parallel implementations of a single contract multiply the surface that must stay in sync and usually signal a missing shared library or service.",
+    why_it_matters: "Every independent reimplementation of a specification is another place a conformance bug can hide and another copy that drifts from the contract. The cost of a spec change scales with the number of reimplementers.",
+    remediation: "Consolidate onto one implementation that the others depend on (`depends_on_product` / `hosts`), or confirm the duplication is deliberate and record why. Capture the stewarding organization with `create_registry_edge` so the contract has an owner.",
+    stages: ["build", "beta", "launch", "growth", "mature"],
+    severity: "low",
+    source: { kind: "fundamental" }
   }
 ];
 function getAntiPatternById(id) {
@@ -24201,6 +24439,7 @@ function evaluateAntiPatterns(inputs, options) {
   const idFilter = options?.anti_pattern_ids ? new Set(options.anti_pattern_ids) : void 0;
   const fires = [];
   for (const ap of UPG_ANTI_PATTERNS) {
+    if (ap.scope === "portfolio" || !ap.structured_condition) continue;
     if (severityFilter && ap.severity !== severityFilter) continue;
     if (idFilter && !idFilter.has(ap.id)) continue;
     if (inputs.productStage && !ap.stages.includes(inputs.productStage)) {
@@ -24361,6 +24600,7 @@ function buildViolation(ap) {
 }
 function collectTargetEntities(cond) {
   const types = /* @__PURE__ */ new Set();
+  if (!cond) return [];
   walk(cond);
   return [...types].sort();
   function walk(c) {
@@ -26692,6 +26932,45 @@ var UPG_REGIONS = [
         crosses_into: "users_needs"
       }
     ]
+  },
+  {
+    id: "foundations",
+    label: "Foundations",
+    order: 11,
+    shape: "polymorphic-target",
+    mental_model: "Shared specs and primitives that many products implement, expose, and conform to.",
+    operators: [
+      "platform architect",
+      "standards author",
+      "staff engineer",
+      "API designer"
+    ],
+    composes_atomic_domains: [
+      "foundations"
+    ],
+    entities: [
+      {
+        type: "specification",
+        role: "anchor"
+      },
+      {
+        type: "primitive",
+        role: "container"
+      }
+    ],
+    anchor: {
+      type: "specification",
+      rationale: "The specification is the rulebook many products point at: they implement, expose, and conform to it, and primitives are defined by it. It is the high-inbound canonical of the Foundations region.",
+      outbound_cross_edge_count: 0,
+      inbound_cross_edge_count: 6
+    },
+    intra_edges: [
+      "specification_extends_specification",
+      "specification_competes_with_specification",
+      "primitive_defined_by_specification",
+      "primitive_composes_primitive"
+    ],
+    boundary_edges: []
   }
 ];
 var UPG_REGION_MAP = Object.fromEntries(UPG_REGIONS.map((r) => [r.id, r]));
@@ -27198,7 +27477,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.9.11";
+var UPG_VERSION = "0.9.13";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -27271,6 +27550,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   DISCOVERY_RESEARCH_VALIDATION_PLAYBOOK,
   ENGINEERING_PLATFORM_PLAYBOOK,
   EXPERIENCE_DESIGN_BRAND_PLAYBOOK,
+  FOUNDATIONS_PLAYBOOK,
   LEGACY_PRODUCT_STAGES,
   MARKDOWN_FORMAT_VERSION,
   MARKET_COMPETITIVE_PLAYBOOK,