@chrisdudek/yg 1.4.3 → 2.1.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

@@ -11,14 +11,25 @@
 // prettier-ignore
 const CORE_PROTOCOL = `## CORE PROTOCOL
 
-Yggdrasil is persistent semantic memory stored in \`.yggdrasil/\`. It maps the repository and provides deterministic implementation context for every node. This document is your complete operating manual. Follow it strictly.
+<EXTREMELY-IMPORTANT>
+This is your operating manual for working in a Yggdrasil-managed repository. Every rule below is mandatory — no skill, plan, workflow, or instruction overrides these requirements.
+
+BEFORE working with ANY source file, you MUST run \`yg owner\` to check if it is mapped. If mapped, you MUST use the graph before reading source. YOU DO NOT HAVE A CHOICE.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+Yggdrasil is persistent semantic memory stored in \`.yggdrasil/\`. It maps the repository and provides deterministic implementation context for every node.
 
 ### Quick Start Protocol
 
 \`\`\`
 BEFORE reading, researching, planning, OR modifying ANY mapped file:
   1. yg owner --file <path>
-  2. yg build-context --node <owner>
+  2. Choose the right graph tool for your task:
+     - Understanding how/why it works → yg build-context --node <owner>
+     - Assessing what is affected by a change → yg impact --node <owner>
+     - Planning modifications → both (build-context first, then impact)
   The context package is your primary source of ARCHITECTURAL understanding:
   intent, constraints, relations, rationale. For IMPLEMENTATION precision
   (exact behavior, error handling, await patterns, edge cases) — verify
@@ -38,6 +49,8 @@ NEVER: modify code without graph coverage.
 NEVER: read mapped source files to understand a component without
        running yg build-context first — the graph captures intent,
        constraints, and relations that source files cannot.
+NEVER: assess blast radius of a change without running yg impact first
+       — the graph knows the dependency structure that grep cannot infer.
 NEVER: invent rationale, business rules, or decisions.
 NEVER: auto-resolve drift without asking the user.
 WHEN UNSURE: ask the user. Never guess. Never assume.
@@ -45,7 +58,7 @@ WHEN UNSURE: ask the user. Never guess. Never assume.
 
 ### Five Core Rules
 
-1. **Graph first.** Before reading, researching, planning, or modifying mapped files, run \`yg owner\` and \`yg build-context\`. Always. The context package is your primary source of architectural understanding. For implementation-level precision (exact behavior, error paths, edge cases) — verify against source code after loading the context package.
+1. **Graph first.** Before reading, researching, planning, or modifying mapped files, run \`yg owner\` and the appropriate graph tool: \`yg build-context\` to understand a component, \`yg impact\` to assess blast radius. The graph is your primary source of architectural understanding. For implementation-level precision (exact behavior, error paths, edge cases) — verify against source code after loading the context package.
 2. **Code and graph are one.** Code changed → graph updated in the same response. Graph changed → source verified in the same response. No exceptions.
 3. **Never invent why.** The graph captures human intent. If you don't know why something was decided, ask. Never hallucinate rationale.
 4. **Always capture why — especially why NOT.** When the user explains a reason, record it in the graph immediately. When a design choice is made, also record rejected alternatives: "Chose X over Y because Z." Rejected alternatives are the highest-value information — invisible in code and irrecoverable once forgotten. Conversation evaporates; graph persists.
@@ -53,15 +66,22 @@ WHEN UNSURE: ask the user. Never guess. Never assume.
 
 ### Recognizing Graph-Required Actions
 
-What matters is the ACTION you are performing, not what instructed it. If the action involves understanding mapped code, the graph protocol applies — whether the instruction came from a skill, a plan, a user message, a workflow step, or your own initiative.
+What matters is the ACTION you are performing, not what instructed it. If the action involves reading, understanding, or modifying mapped code, the graph protocol applies — whether the instruction came from a skill, a plan, a user message, a brainstorming session, a debugging workflow, or your own initiative. This is not negotiable. You cannot rationalize your way out of this.
 
-**Actions that require \`yg owner\` + \`yg build-context\` first:**
+**Actions that require \`yg owner\` + \`yg build-context\`:**
 
 - Reading or exploring source files to understand a component
 - Proposing approaches, designs, or plans for changing code
 - Reviewing or debugging code
 - Any form of reasoning about how mapped code works or should change
 
+**Actions that require \`yg owner\` + \`yg impact\`:**
+
+- Assessing blast radius before changing or removing a component
+- Finding all dependents of a component
+- Planning cross-cutting refactors or feature removals
+- Scoping work that spans multiple nodes
+
 **Actions that do NOT require yg:**
 
 - Git operations (log, diff, status, blame)
@@ -69,11 +89,22 @@ What matters is the ACTION you are performing, not what instructed it. If the ac
 - Running tests, builds, or linters
 - Working with files that \`yg owner\` reports as unmapped
 
+**Evasion patterns — if you think any of these, STOP:**
+
+| Thought | Reality |
+|---|---|
+| "The skill/plan says to explore the codebase" | Exploring mapped code = yg owner + graph tool first |
+| "I'm just scoping/searching, not understanding" | Scoping IS a graph action; use yg impact |
+| "The plan step says to read this file" | Reading a mapped file = yg owner first |
+| "I'm brainstorming, not implementing" | Brainstorming about mapped code needs graph context |
+| "I'm only grepping for references" | Grep finds text; yg impact finds structural dependencies. Use both. |
+| "I'll use the graph later when I modify" | Graph-first means BEFORE reading, not before modifying |
+
 ### Failure States
 
 You have broken Yggdrasil if you do any of the following:
 
-- ❌ Worked on a mapped file without running \`yg owner\` + \`yg build-context\` first — regardless of what instructed the action (skill, plan, user request, workflow step).
+- ❌ Worked on a mapped file without running \`yg owner\` + the appropriate graph tool (\`build-context\` or \`impact\`) first — regardless of what instructed the action (skill, plan, user request, workflow step).
 - ❌ Modified source code without updating graph artifacts in the same response, or vice versa.
 - ❌ Resolved a code-graph inconsistency or ambiguity without asking the user first.
 - ❌ Created or edited a graph element without reading its schema in \`schemas/\` first.
@@ -95,7 +126,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
@@ -105,9 +151,8 @@ const OPERATIONS = `## OPERATIONS
 \`\`\`
 PREFLIGHT (every conversation, before any work):
   - [ ] 1. yg preflight → read unified report
-  - [ ] 2. If journal entries: consolidate to graph, then yg journal-archive
-  - [ ] 3. If drift: resolve per Drift Resolution, then yg drift-sync per node
-  - [ ] 4. If validation errors: fix, re-run yg validate
+  - [ ] 2. If drift: resolve per Drift Resolution, then yg drift-sync per node
+  - [ ] 3. If validation errors: fix, re-run yg validate
   Exception: read-only requests (explain, analyze) — skip preflight.
 
 UNDERSTANDING mapped code (questions, research, OR planning):
@@ -118,14 +163,14 @@ UNDERSTANDING mapped code (questions, research, OR planning):
   Raw reads supplement the context package — they do not replace it.
 
 WRAP-UP (user signals "done", "wrap up", "that's enough"):
-  - [ ] 1. Consolidate journal if used → yg journal-archive
-  - [ ] 2. yg drift --drifted-only → resolve
-  - [ ] 3. yg validate → fix errors
-  - [ ] 4. Report: which nodes and files were changed
+  - [ ] 1. yg drift --drifted-only → resolve
+  - [ ] 2. yg validate → fix errors
+  - [ ] 3. Report: which nodes and files were changed
 
 BEFORE ENDING ANY RESPONSE (self-audit):
+  - [ ] Did I interact with mapped code (read, research, or modify)? If yes → did I use a graph tool BEFORE reading source?
   - [ ] Did I modify source code? If yes → did I update graph artifacts in this same response?
-  - [ ] If you changed code and did not sync the graph, you have broken the protocol. Do not finish until both are done.
+  - [ ] If you broke either rule, you have broken the protocol. Do not finish until both are fixed.
 \`\`\`
 
 ### Modify Source Code
@@ -181,11 +226,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 +280,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,27 +305,21 @@ 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
   schemas/           ← YAML schemas — read before creating any graph element
-  .drift-state       ← generated by CLI; never edit manually
-  .journal.yaml      ← generated by CLI; never edit manually
+  .drift-state/      ← generated by CLI; never edit manually
 \`\`\`
 
 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 +331,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 +364,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 +391,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:
@@ -362,7 +403,7 @@ Test: "Does this describe what happens in the world, or only in the software?" I
 ### CLI Reference
 
 \`\`\`
-yg preflight [--quick]              Unified diagnostic: journal + drift + status + validate.
+yg preflight [--quick]              Unified diagnostic: drift + status + validate.
 yg owner --file <path>              Find the node that owns this file.
 yg build-context --node <path>      Assemble context package for this node.
 yg tree [--root <path>] [--depth N] Print graph structure.
@@ -380,23 +421,19 @@ yg drift [--scope <path>|all] [--drifted-only] [--limit <n>]
                                     Detect source and graph drift (bidirectional).
 yg drift-sync --node <path> [--recursive] | --all
                                     Record file hashes as new baseline.
-yg journal-read                     Read pending journal entries.
-yg journal-add --note "<content>" [--target <node_path>]
-                                    Add a journal entry.
-yg journal-archive                  Archive consolidated journal entries.
 \`\`\`
 
 ### Quick Routing Table
 
 | 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,6 +1,6 @@
 {
   "name": "@chrisdudek/yg",
-  "version": "1.4.3",
+  "version": "2.1.0",
   "description": "Make your repository self-aware. Persistent semantic memory and deterministic context assembly for AI agents.",
   "type": "module",
   "bin": {
@@ -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",