@chrisdudek/yg 4.0.1 → 4.1.0

package/graph-schemas/yg-architecture.yaml

@@ -1,12 +1,39 @@
 # yg-architecture.yaml — Schema for architecture constraints
 # File: .yggdrasil/yg-architecture.yaml
-# Defines node types with architectural constraints.
+#
+# Defines the project's type system: what kinds of nodes exist, how they can
+# relate, and which aspects apply by default. This is the foundation of the
+# graph — every node declares a type, and every type must be defined here.
+#
+# Changes to this file affect the entire graph and should be confirmed with the user.
 # All properties except description are optional — absence means no enforcement.
+# When a constraint is absent, anything is allowed. When present, only listed
+# values are permitted.
 
 node_types:
   <type-id>:
-    description: <string>                    # required — what this type is for
-    aspects: [<aspect-id>]                   # optional — required on every file of this type
-    parents: [<type-id>]                     # optional — allowed parent types
-    relations:                               # optional — allowed relation targets
-      <relation-type>: [<type-id>]           # calls | uses | extends | implements | emits | listens
+    description: <string>                    # required — what this type is for, when to use it
+
+    aspects: [<aspect-id>]                   # optional — aspects automatically applied to every node
+                                             # of this type (channel 3 in aspect resolution).
+                                             # These also cascade to children of nodes of this type
+                                             # (channel 4). Use for invariants that ALL nodes of
+                                             # this type must satisfy.
+
+    parents: [<type-id>]                     # optional — allowed parent node types in the hierarchy.
+                                             # If omitted, this type can appear under any parent.
+                                             # If specified, nesting under an unlisted parent type
+                                             # triggers a parent-type-forbidden error.
+
+    relations:                               # optional — allowed relation targets by relation type.
+                                             # If a relation type is listed, only the specified
+                                             # target types are allowed. Unlisted relation types
+                                             # are unrestricted. If omitted entirely, all relations
+                                             # are allowed.
+      <relation-type>: [<type-id>]           # Relation types:
+                                             #   calls       — runtime invocation
+                                             #   uses        — compile-time dependency
+                                             #   extends     — inheritance / specialization
+                                             #   implements  — interface contract
+                                             #   emits       — publishes events (must pair with listens)
+                                             #   listens     — subscribes to events (must pair with emits)

package/graph-schemas/yg-aspect.yaml

@@ -1,9 +1,20 @@
 # yg-aspect.yaml — Schema for cross-cutting aspects
 # Each aspect is a directory under .yggdrasil/aspects/ containing this file
-# plus any number of .md content files (requirements, rationale, guidance).
-# Aspect identifier = relative path from aspects/ to the directory (e.g. observability/logging).
-# Aspects can be organized in nested directories for hierarchy.
+# plus any number of .md content files.
+#
+# Aspect identifier = relative path from aspects/ to the directory
+# (e.g. observability/logging). Aspects can be organized in nested
+# directories — the directory structure is for organization only,
+# there is no automatic parent-child inheritance between aspects.
+#
+# The .md content files are what the reviewer checks against source code.
+# They should state WHAT must be satisfied and WHY.
 
 name: CrossCuttingRequirementName  # required — display name
-description: "Short description for discovery via yg aspects"  # optional
-# implies: [other-aspect, another-aspect] # optional — other aspect identifiers included automatically (recursive, must be acyclic)
+description: "Short description"   # optional but recommended — shown in yg aspects output
+                                   # and context packages, helps agents discover relevant aspects
+
+# implies: [other-aspect]          # optional — other aspect identifiers included automatically
+                                   # when this aspect is effective on a node. Recursive expansion
+                                   # (A implies B implies C = all three effective). Must be acyclic
+                                   # — CLI detects and rejects cycles.

package/graph-schemas/yg-flow.yaml

@@ -1,10 +1,22 @@
 # yg-flow.yaml — Schema for end-to-end business flows
 # Each flow is a directory under .yggdrasil/flows/ containing this file.
+#
+# A flow describes a business process — what happens in the world,
+# not code call sequences. "User places an order" is a flow.
+# "Handler calls service" is a relation between nodes.
+#
+# Descendants of a declared participant are automatically included —
+# listing a parent node covers all its children.
 
 name: EndToEndProcessName     # required — display name
-description: "Short description of this business process"  # optional
+description: "What this business process does"  # optional but recommended — shown in
+                                                # yg flows output and context packages
+
 nodes:                        # required, non-empty — participant nodes (alias: participants)
   - orders/order-service      # paths relative to model/
-  - payments/payment-service
-  - inventory/inventory-service
-# aspects: [requires-saga]    # optional — aspect tags propagated to ALL participants
+  - payments/payment-service  # each participant (and its descendants) must satisfy
+  - inventory/inventory-service  # any flow-level aspects declared below
+
+# aspects: [requires-saga]    # optional — aspect identifiers propagated to ALL participants
+                              # (channel 5 in aspect resolution). Use for requirements that
+                              # apply to every node in this process but not globally.

package/graph-schemas/yg-node.yaml

@@ -1,23 +1,31 @@
 # yg-node.yaml — Schema for model nodes
 # Every node is a directory under .yggdrasil/model/ containing this file.
+# The node's path in the graph = its directory path relative to model/.
+# Nodes nest by directory — a node at model/orders/handler/ is a child
+# of model/orders/ and inherits its parent's aspects.
 
 name: ComponentName           # required — display name
-type: service                 # required — must match a type from yg-architecture.yaml
-description: "Short description of what this node does"  # optional
+type: service                 # required — must match a type defined in yg-architecture.yaml
+description: "What this node does"  # optional but recommended — shown in context output,
+                                    # helps agents understand purpose without reading code
 
-aspects:                      # optional — list of aspect identifiers
-  - aspect-id                 # aspect directory name under aspects/
+aspects:                      # optional — aspect identifiers applied directly to this node
+  - aspect-id                 # must match a directory name under aspects/
+                              # these aspects also cascade to all child nodes
 
-ports:                        # optional — named entry points with required aspects (on target nodes)
-  port-name:
+ports:                        # optional — named entry points with required aspects
+  port-name:                  # consumers of this node reference ports via consumes
     description: "What this port provides"  # required
-    aspects: [aspect-id]      # required — aspects consumers must satisfy
+    aspects: [aspect-id]      # required — aspects that consumers must satisfy (channel 6)
 
 relations:                    # optional — outgoing dependencies to other nodes
-  - target: other/module-path # required — path relative to model/
+  - target: other/module-path # required — node path relative to model/
     type: calls               # required — calls | uses | extends | implements | emits | listens
-    consumes: [port-name]     # optional — port names consumed from target (required when target has ports)
+    consumes: [port-name]     # optional — port names consumed from target
+                              # required when target declares ports — otherwise check warns
 
-mapping:                      # optional — flat list of source file or directory paths
-  - src/modules/component/    # paths are relative to repository root
-  - src/modules/component.ts
+mapping:                      # optional — source files and directories owned by this node
+  - src/modules/component/    # directory — all files inside are owned (recursive)
+  - src/modules/component.ts  # file — exact match
+                              # paths are relative to repository root
+                              # each source file must have exactly one owner node

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrisdudek/yg",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "Continuous architecture enforcement for AI-assisted development. Aspects, review, enforcement.",
   "type": "module",
   "bin": {