@chrisdudek/yg 1.4.2 → 2.0.0

package/dist/templates/default-config.ts

@@ -1,27 +1,27 @@
-export const DEFAULT_CONFIG = `name: ""
+export const DEFAULT_CONFIG = `version: "2.0.0"
 
-stack:
-  language: ""
-  runtime: ""
-
-standards: ""
+name: ""
 
 node_types:
-  - name: module
-  - name: service
-  - name: library
-  - name: infrastructure
+  module:
+    description: "Business logic unit with clear domain responsibility"
+  service:
+    description: "Component providing functionality to other nodes"
+  library:
+    description: "Shared utility code with no domain knowledge"
+  infrastructure:
+    description: "Guards, middleware, interceptors — invisible in call graphs but affect blast radius"
 
 artifacts:
   responsibility.md:
     required: always
     description: "What this node is responsible for, and what it is not"
-    structural_context: true
+    included_in_relations: true
   interface.md:
     required:
       when: has_incoming_relations
     description: "Public API — methods, parameters, return types, contracts, failure modes, exposed data structures"
-    structural_context: true
+    included_in_relations: true
   internals.md:
     required: never
     description: "How the node works and why — algorithms, business rules, state machines, design decisions with rejected alternatives"

package/dist/templates/rules.ts

@@ -95,7 +95,22 @@ Before preflight:
 
 - Verify \`yg\` CLI is available. If not found, inform user and stop.
 - If \`yg preflight\` shows 0 nodes → enter BOOTSTRAP MODE (see Operations).
-- If drift report shows >10 drifted nodes → report scope to user, ask which area to prioritize. Do not resolve all at once.`;
+- If drift report shows >10 drifted nodes → report scope to user, ask which area to prioritize. Do not resolve all at once.
+
+### Delegating to Subagents
+
+When you delegate work to a subagent (any subprocess, tool agent, or spawned assistant), the subagent does NOT inherit your Yggdrasil knowledge. Before any other instruction, the subagent MUST:
+
+1. Read \`.yggdrasil/agent-rules.md\` — this is the complete operating manual
+2. Follow the Quick Start Protocol from that file before touching any mapped code
+
+Include this as the FIRST instruction in every subagent prompt:
+
+\`\`\`
+BEFORE doing anything else: read .yggdrasil/agent-rules.md and follow its protocol.
+\`\`\`
+
+A subagent that skips this step will read code without graph context, miss architectural constraints, and produce changes that break graph-code consistency.`;
 
 // prettier-ignore
 const OPERATIONS = `## OPERATIONS
@@ -181,11 +196,11 @@ Per area checklist:
 
 - [ ] 1. \`yg owner --file <path>\` — confirm no coverage
 - [ ] 2. Determine node granularity — propose to user if unclear
-- [ ] 3. Create node directory, read \`schemas/node.yaml\`, create \`node.yaml\`
-- [ ] 4. Analyze source — for each artifact type in \`config.artifacts\`: extract content, do not invent
-- [ ] 5. Identify relations — add to \`node.yaml\`
+- [ ] 3. Create node directory, read \`schemas/yg-node.yaml\`, create \`yg-node.yaml\`
+- [ ] 4. Analyze source — for each artifact type in \`yg-config.yaml artifacts\`: extract content, do not invent
+- [ ] 5. Identify relations — add to \`yg-node.yaml\`
 - [ ] 6. Identify cross-cutting requirements — add matching aspects, create if needed
-- [ ] 6b. For each aspect on the node: identify 2-5 code anchors (function names, constants) that evidence the pattern → add to \`node.yaml\` \`anchors\` field
+- [ ] 6b. For each aspect on the node: identify 2-5 code anchors (function names, constants) that evidence the pattern → add as \`anchors\` in the aspect entry in \`yg-node.yaml\`
 - [ ] 7. Identify business process participation — add to flow, ask user if process unclear
 - [ ] 8. \`yg validate\` — fix errors
 - [ ] 9. \`yg drift-sync --node <path>\`
@@ -235,7 +250,7 @@ When reviewing graph quality (triggered by user or quality improvement):
 - [ ] 1. \`yg build-context --node <path>\`
 - [ ] 2. Read mapped source files
 - [ ] 3. For each claim in graph: verify against source code
-- [ ] 4. For each aspect: verify the pattern holds in THIS node. If it deviates, add \`aspect_exceptions\` in \`node.yaml\`
+- [ ] 4. For each aspect: verify the pattern holds in THIS node. If it deviates, add \`exceptions\` to the aspect entry in \`yg-node.yaml\`
 - [ ] 5. Report inconsistencies
 
 **Step 2 — Completeness** (catches MISSING information):
@@ -260,7 +275,7 @@ const KNOWLEDGE_BASE = `## KNOWLEDGE BASE
 
 \`\`\`
 .yggdrasil/
-  config.yaml        ← vocabulary, stack, node types, artifact rules, required aspects
+  yg-config.yaml     ← version, vocabulary, node types, artifact rules, required aspects
   model/             ← what exists: nodes, hierarchy, relations, file mappings
   aspects/           ← what must: cross-cutting requirements with rationale and guidance
   flows/             ← why and in what process: business processes with node participation
@@ -272,15 +287,10 @@ const KNOWLEDGE_BASE = `## KNOWLEDGE BASE
 Key facts:
 
 - **Hierarchy:** nodes nest in \`model/\`. Children inherit parent context. Do not repeat parent content in children.
-- **Aspect id = directory path** under \`aspects/\`. Each aspect has \`aspect.yaml\` + content \`.md\` files. No automatic parent-child — use \`implies\` explicitly.
+- **Aspect id = directory path** under \`aspects/\`. Each aspect has \`yg-aspect.yaml\` + content \`.md\` files. No automatic parent-child — use \`implies\` explicitly.
 - **Flows = business processes.** A flow describes what happens in the world, not code sequences. Flow aspects propagate to all participants.
 
-**Node type guidance:**
-
-- \`module\` — business logic unit with clear domain responsibility
-- \`service\` — component providing functionality to other nodes
-- \`library\` — shared utility code with no domain knowledge
-- \`infrastructure\` — guards, resolvers, middleware, interceptors, validators that intercept or modify request flow. These affect blast radius of changes but are invisible in call graphs. Map them to make blast radius analysis accurate. Key signal: code that runs WITHOUT being explicitly called by business logic (e.g., NestJS guards, Express middleware, GraphQL resolvers).
+**Node type guidance:** Each type in \`yg-config.yaml node_types\` has a \`description\` that tells you when to use it. Check the project's config for the full list and descriptions. Common types: \`module\` (business logic), \`service\` (providing functionality), \`library\` (shared utilities), \`infrastructure\` (guards, middleware, interceptors — invisible in call graphs but affect blast radius).
 
 ### Artifact Structure
 
@@ -292,26 +302,28 @@ Three artifacts capture node knowledge at three levels:
 
 **Enrichment priority (when adding incrementally):** \`interface.md\` first (highest cross-module ROI — contracts enable other nodes to reason about interactions), then \`responsibility.md\` (identity and boundaries), then \`internals.md\` (depth for complex nodes). A node with only \`interface.md\` provides more cross-module value than one with only \`internals.md\`.
 
+Projects can define additional artifact types in \`yg-config.yaml\` under \`artifacts\`. Each custom artifact has a \`description\` (tells you what to write), a \`required\` condition (\`always\`, \`never\`, \`when: has_incoming_relations\`, \`when: has_aspect:<id>\`), and an \`included_in_relations\` flag (if true, included in dependency context packages for structural relations). The three standard artifacts are always present in config. Check \`yg-config.yaml\` to see all defined artifacts for the project.
+
 ### Context Assembly
 
-Run \`yg build-context --node <path>\` to get the deterministic context package for a node. The package assembles global config, hierarchy, own artifacts, aspects, and relational context. It is your architectural map. For implementation-level claims (exact call patterns, error handling, await vs fire-and-forget) — verify against source code. If the package is insufficient, enrich the graph.
+Run \`yg build-context --node <path>\` to get the deterministic context package for a node. The package assembles global project identity, hierarchy, own artifacts, aspects, and relational context. It is your architectural map. For implementation-level claims (exact call patterns, error handling, await vs fire-and-forget) — verify against source code. If the package is insufficient, enrich the graph.
 
 ### Information Routing
 
 When you encounter information, route it to the correct location:
 
-- **Specific to this node** → local node artifact (check \`config.yaml artifacts\` for available types)
-- **Rule for many nodes** → aspect (\`aspects/<id>/\` with \`aspect.yaml\` + content \`.md\` files). If applies to ALL nodes of a type → \`node_types[*].required_aspects\` in \`config.yaml\`
-- **Business process** → flow (\`flows/<name>/\` with \`flow.yaml\` + \`description.md\`). Ask user if process unclear.
+- **Specific to this node** → local node artifact (check \`yg-config.yaml artifacts\` for available types)
+- **Rule for many nodes** → aspect (\`aspects/<id>/\` with \`yg-aspect.yaml\` + content \`.md\` files). If applies to ALL nodes of a type → \`node_types.<type>.required_aspects\` in \`yg-config.yaml\`
+- **Business process** → flow (\`flows/<name>/\` with \`yg-flow.yaml\` + \`description.md\`). Ask user if process unclear.
 - **Shared across a domain** → parent node artifact. Children receive it through hierarchy.
-- **Technology stack or standard** → \`config.yaml\` under \`stack\` or \`standards\` (+ \`rationale\` field)
-- **Decision (why + why NOT):** one node → Decisions section of \`internals.md\` with format "Chose X over Y because Z"; category of nodes → aspect content files; tech choice → \`config.yaml\` rationale field. Always include rejected alternatives — they are the highest-value graph content. If the rationale is unknown: record the decision with "rationale: unknown" and note what CAN be observed from the code. Never invent a plausible-sounding rationale.
+- **Technology stack or standard** → node artifact at the appropriate hierarchy level (e.g., root node's \`responsibility.md\` for single-stack repos, or deployment unit node for monorepos)
+- **Decision (why + why NOT):** one node → Decisions section of \`internals.md\` with format "Chose X over Y because Z"; category of nodes → aspect content files; tech choice → node artifact at the level where the technology applies. Always include rejected alternatives — they are the highest-value graph content. If the rationale is unknown: record the decision with "rationale: unknown" and note what CAN be observed from the code. Never invent a plausible-sounding rationale.
 
 ### Creating Aspects
 
-- [ ] 1. Read \`schemas/aspect.yaml\`
+- [ ] 1. Read \`schemas/yg-aspect.yaml\`
 - [ ] 2. Create \`aspects/<id>/\` directory
-- [ ] 3. Write \`aspect.yaml\` — name, optional description, optional implies
+- [ ] 3. Write \`yg-aspect.yaml\` — name, optional description, optional implies
 - [ ] 4. Write content \`.md\` files: WHAT must be satisfied + WHY (user's words, do not invent)
 - [ ] 5. \`yg validate\`
 
@@ -323,23 +335,23 @@ Test: "Does this requirement apply to more than one node?" Yes → aspect. No
 - **Architectural:** Structural patterns with rationale (e.g., dual-rollback on provider failure, idempotency via key generation, fire-and-forget dispatch)
 - **Concurrency:** Shared concurrency strategies (e.g., pessimistic locking, retry-on-deadlock, optimistic versioning)
 
-When a node follows an aspect's pattern with exceptions, record exceptions in \`node.yaml\` under \`aspect_exceptions\`. Example: aspect says "fire-and-forget" but this node awaits the publish call. The exception appears in the context package next to the aspect content, preventing abstractions from masking implementation details.
+When a node follows an aspect's pattern with exceptions, record them in the \`exceptions\` field of the aspect entry in \`yg-node.yaml\`. Example: aspect says "fire-and-forget" but this node awaits the publish call — add \`exceptions: ["awaits publish call instead of fire-and-forget because..."]\`. Exceptions appear in the context package next to the aspect content, preventing abstractions from masking implementation details.
 
 **Aspect lifecycle warning.** Aspects decay CATASTROPHICALLY — a pattern either exists or it doesn't. When a pattern changes, ALL aspect claims become wrong at once. This differs from other artifacts: \`interface.md\` and \`responsibility.md\` are most stable (~9-year half-life); \`internals.md\` has moderate stability (~2.5-year half-life); aspects are least stable (~2.4-year half-life, binary decay). After any significant feature addition, review ALL aspects touching the affected area. Don't wait for drift — aspects can be 100% wrong without any mapped file changing.
 
-**Aspect stability tiers.** If an aspect has a \`stability\` field in \`aspect.yaml\`, use it to calibrate review urgency:
+**Aspect stability tiers.** If an aspect has a \`stability\` field in \`yg-aspect.yaml\`, use it to calibrate review urgency:
 
 - \`schema\` — enforced by data model; review only when data model changes (most stable)
 - \`protocol\` — contractual pattern; review when contracts or interfaces change
 - \`implementation\` — specific mechanism; review after ANY significant code change (least stable)
 
-When code anchors (\`anchors\` field in \`node.yaml\`) are present for an aspect, they list code patterns (function names, constants, SQL fragments) evidencing the aspect's implementation in this node. \`yg validate\` checks that each anchor exists in the node's mapped source files — a missing anchor (W014) signals the aspect may be stale for this node.
+When code anchors (\`anchors\` in an aspect entry in \`yg-node.yaml\`) are present, they list code patterns (function names, constants, SQL fragments) evidencing the aspect's implementation in this node. \`yg validate\` checks that each anchor exists in the node's mapped source files — a missing anchor (W014) signals the aspect may be stale for this node.
 
 ### Creating Flows
 
-- [ ] 1. Read \`schemas/flow.yaml\`
+- [ ] 1. Read \`schemas/yg-flow.yaml\`
 - [ ] 2. Create \`flows/<name>/\` directory
-- [ ] 3. Write \`flow.yaml\` — declare participants and flow-level aspects
+- [ ] 3. Write \`yg-flow.yaml\` — declare participants and flow-level aspects
 - [ ] 4. Write \`description.md\` with required sections: Business context, Trigger, Goal, Participants, Paths (at least Happy path), Invariants across all paths
 - [ ] 5. \`yg validate\`
 
@@ -350,7 +362,7 @@ Test: "Does this describe what happens in the world, or only in the software?" I
 ### Operational Rules
 
 - **English only** for all files in \`.yggdrasil/\`. Conversation can be any language.
-- **Read schemas before creating** any \`node.yaml\`, \`aspect.yaml\`, or \`flow.yaml\`.
+- **Read schemas before creating** any \`yg-node.yaml\`, \`yg-aspect.yaml\`, or \`yg-flow.yaml\`.
 - **Tools read, you write.** The \`yg\` CLI only reads, validates, and manages metadata. You create and edit files manually.
 - **Incremental sync.** Run \`yg drift-sync\` after every 3-5 source file changes. Do not defer to end of task.
 - **Completeness test:** Two checks, both required:
@@ -390,13 +402,13 @@ yg journal-archive                  Archive consolidated journal entries.
 
 | What you have | Where it goes |
 |---|---|
-| Information specific to this node | Local node artifact (check \`config.yaml artifacts\` for types) |
+| Information specific to this node | Local node artifact (check \`yg-config.yaml artifacts\` for types) |
 | Rule that applies to many nodes | Aspect (content \`.md\` files in \`aspects/<id>/\`) |
-| Architectural invariant for a node type | Required aspect in \`config.yaml node_types\` |
-| Business process participation | Flow (\`flow.yaml participants\`) |
+| Architectural invariant for a node type | Required aspect in \`yg-config.yaml node_types\` |
+| Business process participation | Flow (\`yg-flow.yaml participants\`) |
 | Process-level requirement | Flow \`aspects\` + aspect directory |
 | Context shared across a domain | Parent node artifact |
-| Technology stack | \`config.yaml stack\` (+ \`rationale\` field) |
-| Global coding standards | \`config.yaml standards\` |`;
+| Technology stack | Node artifact at appropriate hierarchy level |
+| Coding standards | Node artifact at appropriate hierarchy level |`;
 
 export const AGENT_RULES_CONTENT = [CORE_PROTOCOL, OPERATIONS, KNOWLEDGE_BASE].join('\n\n---\n\n') + '\n';

package/graph-schemas/{aspect.yaml → yg-aspect.yaml}

@@ -1,4 +1,4 @@
-# aspect.yaml — Schema for cross-cutting aspects
+# 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).
@@ -7,3 +7,7 @@
 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)
+# stability: protocol        # optional — schema | protocol | implementation
+                              # schema = enforced by data model (most stable)
+                              # protocol = enforced by convention/contract
+                              # implementation = specific mechanism (least stable, review after any code change)

package/graph-schemas/{config.yaml → yg-config.yaml}

@@ -1,7 +1,11 @@
-# config.yaml — Schema for the Yggdrasil project configuration
-# Located at .yggdrasil/config.yaml — one per project.
+# yg-config.yaml — Schema for the Yggdrasil project configuration
+# Located at .yggdrasil/yg-config.yaml — one per project.
 # Edit this after running yg init to describe your project.
 
+version: "2.0.0"                  # managed by CLI — do not edit manually. Tracks the CLI version
+                                  # that created or last migrated this config. Used by the migration
+                                  # system to determine which migrations to run on upgrade.
+
 name: "My Project"               # required — project display name
 
 stack:                            # required — technology stack (freeform keys)
@@ -13,22 +17,25 @@ stack:                            # required — technology stack (freeform keys
 
 standards: ""                     # optional — global coding conventions (free text)
 
-node_types:                       # required — allowed node type names
-  - name: module                  #   each type needs at least a 'name'
+node_types:                       # required — non-empty object of node type definitions
+  module:                         #   key = type name used in yg-node.yaml
+    description: "Business logic unit with clear domain responsibility"
     # required_aspects: []        #   optional — aspects every node of this type must have
-  - name: service
-  - name: library
+  service:
+    description: "Component providing functionality to other nodes"
+  library:
+    description: "Shared utility code with no domain knowledge"
 
 artifacts:                        # required — artifact type definitions
   responsibility.md:              #   key = filename in node directories
     required: always              #   always | never | { when: <condition> }
     description: "What this node is responsible for, and what it is not"
-    structural_context: true      #   true = included in dependency context packages
+    included_in_relations: true      #   true = included in dependency context packages
   interface.md:
     required:
       when: has_incoming_relations  # conditions: has_incoming_relations, has_outgoing_relations, has_aspect:<id>
     description: "Public API — methods, parameters, return types, contracts"
-    structural_context: true
+    included_in_relations: true
   # Additional artifact types: logic.md, constraints.md, errors.md, model.md, state.md, decisions.md
 
 quality:                          # optional — quality thresholds

package/graph-schemas/{flow.yaml → yg-flow.yaml}

@@ -1,4 +1,4 @@
-# flow.yaml — Schema for end-to-end business flows
+# yg-flow.yaml — Schema for end-to-end business flows
 # Each flow is a directory under .yggdrasil/flows/ containing this file
 # plus description.md with required sections (see rules).
 

package/graph-schemas/{node.yaml → yg-node.yaml}

@@ -1,12 +1,19 @@
-# node.yaml — Schema for model nodes
+# yg-node.yaml — Schema for model nodes
 # Every node is a directory under .yggdrasil/model/ containing this file
-# plus artifact .md files defined in config.yaml.
+# plus artifact .md files defined in yg-config.yaml.
 
 name: ComponentName           # required — display name
 type: service                 # required — must match a type from config.node_types
-aspects: []                   # optional — list of aspect identifiers (directory paths under aspects/)
 blackbox: false               # optional, default false — if true, coarse-grained coverage without deep artifacts
 
+aspects:                      # optional — list of aspect configurations
+  - aspect: aspect-id         # required — aspect identifier (directory path under aspects/)
+    exceptions:               # optional — how this node deviates from the aspect's pattern
+      - "Description of deviation and why"
+    anchors:                  # optional — code patterns for aspect staleness detection
+      - functionName          # yg validate checks each pattern exists in mapped source files (W014)
+      - CONSTANT_NAME
+
 relations:                    # optional — outgoing dependencies to other nodes
   - target: other/module-path # required — path relative to model/
     type: calls               # required — calls | uses | extends | implements | emits | listens

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@chrisdudek/yg",
-  "version": "1.4.2",
+  "version": "2.0.0",
   "description": "Make your repository self-aware. Persistent semantic memory and deterministic context assembly for AI agents.",
   "type": "module",
   "bin": {
-    "yg": "./dist/bin.js"
+    "yg": "dist/bin.js"
   },
   "files": [
     "dist/",
@@ -43,7 +43,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/krzysztofdudek/Yggdrasil.git",
+    "url": "git+https://github.com/krzysztofdudek/Yggdrasil.git",
     "directory": "source/cli"
   },
   "publishConfig": {
@@ -53,11 +53,13 @@
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "ignore": "^7.0.5",
+    "semver": "^7.7.4",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^25.3.0",
+    "@types/semver": "^7.7.1",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^10.0.1",
     "prettier": "^3.8.1",