@chrisdudek/yg 0.3.4 → 1.1.0

package/dist/bin.js

@@ -17,12 +17,10 @@ stack:
 
 standards: ""
 
-tags: []
-
 node_types:
-  - module
-  - service
-  - library
+  - name: module
+  - name: service
+  - name: library
 
 artifacts:
   responsibility.md:
@@ -56,21 +54,12 @@ artifacts:
     required: never
     description: "Local design decisions and rationale \u2014 choices specific to this node, not system-wide"
 
-knowledge_categories:
-  - name: decisions
-    description: "Global semantic decisions and their rationale"
-  - name: patterns
-    description: "Implementation conventions with examples"
-  - name: invariants
-    description: "System truths that must never be violated"
-
 quality:
   min_artifact_length: 50
   max_direct_relations: 10
   context_budget:
     warning: 10000
     error: 20000
-  knowledge_staleness_days: 90
 `;
 
 // src/templates/platform.ts
@@ -78,244 +67,319 @@ import { readFile, writeFile, mkdir } from "fs/promises";
 import path from "path";
 
 // src/templates/rules.ts
-var AGENT_RULES_CONTENT = `# Yggdrasil - System Semantic Memory (Operating Manual)
-
-You are working in a repository managed by Yggdrasil.
-Yggdrasil is a persistent, structured semantic memory graph stored in \`.yggdrasil/\`. It maps the repository, dictates system rules, and assembles implementation contexts.
-
-**Why:** AI agents degrade with project size \u2014 too little context breaks contracts, too much context drowns in noise. The graph is persistent semantic memory: agents need exactly the right tokens for the task, not the whole repo. Small, precise context beats massive noisy. A repository with Yggdrasil is self-aware.
-
-THIS PROMPT IS YOUR ENTIRE OPERATING MANUAL. Read it carefully. Follow it strictly.
-
----
-
-## 0. ATOMIC INVARIANT \u2014 OVERRIDES EVERYTHING
-
-**CODE \u2194 GRAPH ARE ONE.**
-- Code changed \u2192 graph artifacts MUST be updated IN THE SAME RESPONSE. No exceptions.
-- Graph changed \u2192 source files MUST be verified/updated IN THE SAME RESPONSE. No exceptions.
-- There is NO "code-only" response. There is NO "graph-only" response (unless explicitly a dry-run plan).
-- If you complete a response and one side is changed but the other is not, you have VIOLATED the core contract of Yggdrasil.
-
----
-
-## 1. CORE PRINCIPLES (NON-NEGOTIABLE)
-
-1. **Graph First, Always:** Before answering a question, modifying code, or planning a feature, you MUST consult the graph.
-2. **Context is Sufficient:** If you feel the need to randomly explore source files to understand what a node should do, the graph is incomplete. **Fix the graph** (add decisions, interface details, constraints). Do not bypass the graph by reading raw code.
-3. **Graph is Intended Truth:** If the code and graph diverge, the graph is the truth. If a code change is deliberate, update the graph to match.
-4. **Exhaustive Coverage:** Every source file MUST belong to exactly one graph node. No orphaned files.
-5. **Tools Read, You Write:** The \`yg\` CLI tools only read, validate, and manage metadata. YOU must create and edit graph directories, \`.yaml\` files, and \`.md\` artifacts manually.
-6. **English Only for Artifacts:** All graph artifact files (filenames from \`config.artifacts\`, in the same directory as \`node.yaml\`) MUST be written in English. Conversation can be in the user's language.
-7. **Never Touch Operational Metadata:** NEVER manually edit \`.yggdrasil/.drift-state\` or \`.yggdrasil/.journal.yaml\`.
-8. **Ask, Never Infer:** If graph and code diverge in a way with multiple valid resolutions, or if a required decision is ambiguous \u2014 STOP. State the ambiguity. List interpretations. Ask the user to decide. Never silently choose. Never patch without confirmation. When you stop, always explain the context and available options clearly so the user can make an informed choice.
-
----
-
-## 1.5 FAILURE STATES
+var 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.
+
+### Quick Start Protocol
+
+\`\`\`
+BEFORE reading, researching, planning, OR modifying ANY mapped file:
+  1. yg owner --file <path>
+  2. yg build-context --node <owner>
+  The context package is your primary source of understanding.
+  Raw file reads are for implementation details WITHIN a node you
+  already understand from its context package.
+  If the context package seems insufficient \u2014 enrich the graph.
+  Do not bypass it.
+
+AFTER modifying:
+  3. Update graph artifacts to reflect changes
+  4. yg validate \u2014 fix all errors
+  5. yg drift-sync --node <owner>
+
+EVERY conversation start:
+  yg preflight \u2192 act on findings (see Operations)
+
+NEVER: modify code without graph coverage.
+NEVER: read mapped source files to understand a component without
+       running yg build-context first \u2014 the graph captures intent,
+       constraints, and relations that source files cannot.
+NEVER: invent rationale, business rules, or decisions.
+NEVER: auto-resolve drift without asking the user.
+WHEN UNSURE: ask the user. Never guess. Never assume.
+\`\`\`
+
+### Five Core Rules
 
-You have fundamentally broken Yggdrasil if you do any of the following:
-- \u274C You modified source code without having run \`yg owner --file <path>\` for each modified file in the SAME response.
-- \u274C You modified source code without updating graph artifacts in the SAME response.
-- \u274C You modified graph files without verifying/updating source code alignment in the SAME response.
-- \u274C You resolved a code\u2194graph inconsistency without asking the user first.
-- \u274C You created or edited a graph element without reading its schema in \`.yggdrasil/templates/\`.
-- \u274C You ran \`yg drift-sync\` before updating graph artifacts.
-- \u274C You ran \`yg drift-sync\` after a graph-only change without verifying source files.
-- \u274C You used Blackbox coverage for greenfield/new code.
-- \u274C You answered a question about a mapped file/area without running \`yg build-context\` when the path was known.
+1. **Graph first.** Before reading, researching, planning, or modifying mapped files, run \`yg owner\` and \`yg build-context\`. Always. The context package \u2014 not raw source \u2014 is your primary source of understanding.
+2. **Code and graph are one.** Code changed \u2192 graph updated in the same response. Graph changed \u2192 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 \u2014 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 \u2014 invisible in code and irrecoverable once forgotten. Conversation evaporates; graph persists.
+5. **Ask before resolving ambiguity.** When multiple valid interpretations exist, stop, list options, ask the user. Never silently choose.
 
----
-
-## 2. CONVERSATION LIFECYCLE (YOUR HABITS)
-
-You do not need explicit "session" commands. Follow these conversational triggers:
-
-### A. Preflight (First message of the conversation)
-Always execute these commands before doing anything else. *(Exception: If the user's request is clearly read-only, run ONLY step 1).* **Read-only** means the user asks only for explanation, clarification, analysis, or evaluation \u2014 no code or graph modification will occur. Examples: "explain this", "evaluate X", "what does Y do?", "analyze Z". If unsure, run full preflight.
-1. \`yg journal-read\` -> If entries exist, consolidate them into the graph, then \`yg journal-archive\`.
-2. \`yg drift\` -> If **drift** (code changed, graph baseline stale): run \`yg drift-sync\` for each affected node. Do NOT ask the user \u2014 they do not need to know this step. If **missing** or **unmaterialized**: report and ask the user how to proceed.
-3. \`yg status\` -> Report graph health.
-4. \`yg validate\` -> If W008 stale-knowledge appears, update the knowledge artifacts to reflect current node state.
-
-### B. Answering Questions (When a specific file or area is known)
-When the user asks a question and you know (or can infer) which file or area of the codebase it concerns:
-1. Run \`yg owner --file <path>\` for the relevant file(s).
-2. **If owner FOUND:** Run \`yg build-context --node <node_path>\` and base your answer on that context. Do NOT answer from grep/search alone \u2014 the graph provides intent, constraints, and relations that yield better answers.
-3. **If owner NOT FOUND:** The file is outside the graph (e.g. third-party code, user's theme/plugin, unmapped area). You may answer from grep/search, but state that the answer is not graph-based.
-
-This applies even when you are **not modifying files** \u2014 e.g. when providing code snippets to paste elsewhere, explaining behavior, or suggesting hooks. If the question touches mapped code, build-context first.
-
-### C. Session Verification (Wrap-up)
-Triggered by phrases like: "we're done", "wrap up", "that's enough", "done", "ok".
-**Note: The graph should ALREADY be up to date. If the graph requires massive updates at this stage, YOU HAVE FAILED.**
-1. If iterative journal mode was used: consolidate notes to the graph, then \`yg journal-archive\`.
-2. \`yg drift\` -> If drift detected, run \`yg drift-sync\` for each affected node. Do NOT ask \u2014 absorb automatically.
-3. \`yg validate\` -> Fix any structural errors.
-4. Report exactly what nodes and files were changed.
-
----
-
-## 3. WORKFLOW: MODIFYING OR CREATING FILES (Code-First)
-
-You are NOT ALLOWED to edit or create source code without establishing graph coverage first.
-
-**Gate:** Before using any tool that modifies files, you MUST have run \`yg owner --file <path>\` for each file you intend to modify. If you have not \u2014 run it first, then proceed. No exceptions. Gate applies to **source files** (files outside \`.yggdrasil/\`). For graph files (\`.yggdrasil/model/\`, \`.yggdrasil/aspects/\`, etc.), follow the Graph Modification Checklist in section 4 instead.
+### Failure States
 
-**Step 1: Check coverage** -> Run \`yg owner --file <path>\`
+You have broken Yggdrasil if you do any of the following:
+
+- \u274C Modified source code without running \`yg owner --file <path>\` first.
+- \u274C Modified source code without updating graph artifacts in the same response.
+- \u274C Modified graph files without verifying source code alignment in the same response.
+- \u274C Resolved a code-graph inconsistency without asking the user first.
+- \u274C Created or edited a graph element without reading its schema in \`schemas/\` first.
+- \u274C Ran \`yg drift-sync\` before updating graph artifacts.
+- \u274C Wrote a flow description that describes code sequences instead of a business process.
+- \u274C Used an aspect identifier that has no corresponding \`aspects/\` directory.
+- \u274C Placed a cross-cutting requirement in a local node artifact instead of an aspect.
+- \u274C Invented a rationale, business rule, or architectural decision.
+- \u274C Used blackbox coverage for greenfield (new) code.
+- \u274C Answered a question about a mapped file without running \`yg build-context\` first.
+- \u274C Read mapped source files to plan or research changes without running \`yg build-context\` first.
+- \u274C Deferred \`yg drift-sync\` to the end of a multi-step task instead of running it incrementally after each logical group of changes.
+- \u274C Recorded a design decision without documenting which alternatives were rejected and why.
+
+### Escape Hatch
 
-**Step 2: If Owner FOUND (The Execution Checklist)**
-Whenever you write or edit source code, you MUST output this exact checklist in your response to the user, and execute each step BEFORE finishing your turn:
+If the user explicitly requests a code-only change, comply but:
 
-- [ ] 1. Read Specification (ran \`yg build-context\`)
-- [ ] 2. Modify Source Code
-- [ ] 3. Sync Graph Artifacts (manually edit the node's artifact files IMMEDIATELY to match new code behavior)
-- [ ] 4. Baseline Hash (ran \`yg drift-sync\` ONLY AFTER updating the graph)
+- Warn: "This creates drift. Run \`yg drift\` next session to reconcile."
+- Do NOT run \`yg drift-sync\` \u2014 leave the drift visible.
+
+### Environment Check
 
-**Step 3: If Owner NOT FOUND (Uncovered Area)**
-STOP. Do not modify the code. First determine: **Is this greenfield or existing code?**
-
-* **If GREENFIELD (empty directory, new project):** Do NOT offer blackbox. Create proper nodes (reverse engineering or upfront design) before implementing.
-* **If PARTIALLY MAPPED (file is unmapped, but lives inside a mapped module):** Stop and ask the user if this file should be added to the existing node or if a new node is required.
-* **If EXISTING CODE (legacy, third-party):** Present the user with 3 options and wait:
-  * **Option 1: Reverse Engineering:** Create/extend standard nodes to map the area fully before modifying.
-  * **Option 2: Blackbox Coverage:** Create a \`blackbox: true\` node to establish ownership without deep semantic exploration.
-  * **Option 3: Abort/Change Plan:** Do not touch the file.
-
-**Reverse engineering order:** When reverse-engineering an area, create graph elements in this order: (1) aspects, (2) flows, (3) knowledge elements, (4) model nodes. Never create model nodes before cross-cutting rules and shared wisdom exist \u2014 they depend on them.
-
----
+Before preflight:
 
-## 4. WORKFLOW: MODIFYING THE GRAPH & BLAST RADIUS (Graph-First)
+- Verify \`yg\` CLI is available. If not found, inform user and stop.
+- If \`yg preflight\` shows 0 nodes \u2192 enter BOOTSTRAP MODE (see Operations).
+- If drift report shows >10 drifted nodes \u2192 report scope to user, ask which area to prioritize. Do not resolve all at once.`;
+var OPERATIONS = `## OPERATIONS
 
-When adding features, changing architecture, or doing graph-first design:
+### Conversation Lifecycle
 
-1. **Check Blast Radius:** Before modifying a node that others depend on, run \`yg impact --node <node_path> --simulate\`. Report the impact to the user.
-2. **Read Config & Templates:**
-   * Check \`.yggdrasil/config.yaml\` for allowed \`node_types\` and \`tags\`.
-   * **CRITICAL:** ALWAYS read the schema in \`.yggdrasil/templates/\` for the element type (node.yaml, aspect.yaml, flow.yaml, knowledge.yaml) before creating or editing it.
-3. **Validate & Fix:** Run \`yg validate\`. You must fix all E-codes (Errors).
-4. **Token Economy & W-codes:**
-   * W005/W006: Context package too large. Consider splitting the node.
-   * W008: Stale semantic memory. Update knowledge artifacts.
+\`\`\`
+PREFLIGHT (every conversation, before any work):
+  - [ ] 1. yg preflight \u2192 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
+  Exception: read-only requests (explain, analyze) \u2014 skip preflight.
 
-**Graph Modification Checklist**
-Whenever you change the graph structure or semantics, you MUST output and execute this exact checklist:
+UNDERSTANDING mapped code (questions, research, OR planning):
+  - [ ] 1. yg owner --file <path>
+  - [ ] 2. Owner found \u2192 yg build-context --node <path>. Use context package as primary source.
+  - [ ] 3. Owner not found \u2192 use file analysis, state it is not graph-backed.
+  Never use grep or raw file reads as primary understanding when graph coverage exists.
+  Raw reads supplement the context package \u2014 they do not replace it.
 
-- [ ] 1. Read schema from \`.yggdrasil/templates/\` (node.yaml, aspect.yaml, flow.yaml, or knowledge.yaml for the element type)
-- [ ] 2. Edit graph files (\`node.yaml\`, artifacts)
-- [ ] 3. Verify corresponding source files exist and their behavior matches updated artifacts
-- [ ] 4. Validate (ran \`yg validate\` \u2014 fix all Errors)
-- [ ] 5. Baseline Hash (ran \`yg drift-sync\` ONLY AFTER steps 2-3 are confirmed)
+WRAP-UP (user signals "done", "wrap up", "that's enough"):
+  - [ ] 1. Consolidate journal if used \u2192 yg journal-archive
+  - [ ] 2. yg drift --drifted-only \u2192 resolve
+  - [ ] 3. yg validate \u2192 fix errors
+  - [ ] 4. Report: which nodes and files were changed
+\`\`\`
 
-**Journaling (Iterative Mode Scope):**
-* **Default:** Write changes directly to graph files immediately. Do not defer.
-* **Opt-in:** ONLY if the user says "use iterative mode" or "use journal". Once activated, it remains active for the ENTIRE conversation until wrap-up. Use \`yg journal-add --note "..."\` to buffer intent.
+### Modify Source Code
 
----
+You are not allowed to edit or create source code without establishing graph coverage first.
 
-## 5. PATH CONVENTIONS (CRITICAL)
+**Step 1** \u2014 Check coverage: \`yg owner --file <path>\`
 
-To avoid broken references (\`E004\`, \`E005\`), use correct relative paths:
-* **Node paths** (used in CLI, relations, flow nodes): Relative to \`.yggdrasil/model/\` (e.g., \`orders/order-service\`).
-* **File paths** (used in mapping, \`yg owner\`): Relative to the repository root (e.g., \`src/modules/orders/order.service.ts\`).
-* **Knowledge paths** (used in node explicit refs): Relative to \`.yggdrasil/knowledge/\` (e.g., \`decisions/001-event-sourcing\`).
+**Step 2a** \u2014 Owner found: execute checklist:
 
----
+- [ ] 1. Read specification: \`yg build-context --node <node_path>\`
+- [ ] 2. Assess blast radius: \`yg impact --node <node_path>\` \u2014 review dependents, descendants, and co-aspect nodes before changing interfaces or shared behavior
+- [ ] 3. Modify source code
+- [ ] 4. Sync graph artifacts \u2014 edit artifact files to reflect the changes
+- [ ] 5. Run \`yg validate\` \u2014 fix all errors (if unfixable after 3 attempts \u2192 stop, report to user)
+- [ ] 6. Run \`yg drift-sync --node <node_path>\` \u2014 only after graph and code are both current
 
-## 6. GRAPH STRUCTURE, CONFIG & TEMPLATES CHEAT SHEET
+**Step 2b** \u2014 Owner not found: establish coverage first. Present options to the user:
 
-The graph lives entirely under \`.yggdrasil/\`. You NEVER guess structure. You MUST ALWAYS read the corresponding schema reference in \`.yggdrasil/templates/\` before creating or editing any graph file.
+*Partially mapped* (file unmapped but inside a mapped module): ask whether to add to existing node or create new one.
 
-* **\`.yggdrasil/config.yaml\`**: Defines \`node_types\`, \`tags\`, \`artifacts\`, \`knowledge_categories\`.
-* **\`.yggdrasil/templates/\`**: Schemas for each graph layer \u2014 \`node.yaml\`, \`aspect.yaml\`, \`flow.yaml\`, \`knowledge.yaml\`.
-* **\`.yggdrasil/model/\`**: Node tree. Each node is a directory with \`node.yaml\` and artifact files.
-* **\`.yggdrasil/aspects/\`**: Cross-cutting rules. Directory contains \`aspect.yaml\` and \`.md\` content.
-* **\`.yggdrasil/flows/\`**: End-to-end processes. Directory contains \`flow.yaml\` and \`.md\` content.
-* **\`.yggdrasil/knowledge/\`**: Repo-wide wisdom. Directory contains \`knowledge.yaml\` and \`.md\` content.
+*Existing code:*
 
----
+- Option A \u2014 Full node: create node(s), map files, write artifacts from code analysis
+- Option B \u2014 Blackbox: create a blackbox node at agreed granularity
+- Option C \u2014 Abort
 
-## 7. CONTEXT ASSEMBLY & KNOWLEDGE DECONSTRUCTION (HOW TO MAP FILES)
+*Greenfield (new code):* Only Option A. Blackbox is forbidden for new code. Follow the graph-first workflow:
 
-Your ultimate goal when describing a file or node is **Context Reproducibility**. A future agent reading ONLY the output of \`yg build-context\` for this node must be able to perfectly reconstruct the source code's behavior, constraints, environment, and purpose.
+1. Create aspects first (cross-cutting requirements the new code must satisfy)
+2. Create flows if the code participates in a business process
+3. Create nodes with full artifacts \u2014 responsibility, constraints, decisions, interface, logic
+4. Review the context package (\`yg build-context\`) \u2014 it is now the behavioral specification
+5. Implement code that satisfies the specification
+6. The graph specifies WHAT and WHY; the code implements HOW (framework APIs, library choices)
 
-However, you must NOT dump all knowledge into a single file. Yggdrasil's context package is **multi-layered** and hierarchically assembled. When you map existing code or design new code, you must deconstruct the knowledge and place it at the correct abstraction layer so the engine can mechanically reassemble it.
+After the user chooses, return to Step 1 and follow Step 2a.
 
-### CRITICAL RULE: CAPTURE INTENT, BUT NEVER INVENT IT
-The graph is not just a structural map; it is the semantic meaning of the system. Code explains "what" and "how". The graph MUST explain "WHY".
+### Modify Graph
 
-1. **ALWAYS Capture the User's "Why":** If the user explains the business reason, intent, or rationale behind a request (e.g., "We need to do X because Y"), you MUST permanently record this reasoning in the relevant graph artifacts (from \`config.artifacts\` that fit the content). Do not let the conversation context evaporate.
-2. **NEVER Invent the "Why":** Artifacts that imply human judgment (e.g. local decisions, \`knowledge/invariants\`) must reflect ACTUAL human choices.
-3. **NO Hallucinations:** You MUST NEVER infer or hallucinate a rationale, an architectural decision, or a business rule.
-4. **Ask if Missing:** If the user requests a significant architectural or business logic change but does not provide the rationale, you MUST ask them "Why are we making this change?" before documenting the decision in the graph.
+- [ ] 1. Read the relevant schema from \`schemas/\` before touching any YAML
+- [ ] 2. Before changing an aspect or flow, check scope: \`yg impact --aspect <id>\` or \`yg impact --flow <name>\` \u2014 understand which nodes are affected before modifying shared rules or processes
+- [ ] 3. Make changes
+- [ ] 4. Run \`yg validate\` immediately \u2014 fix all errors
+- [ ] 5. Verify affected source files are consistent \u2014 update if needed
+- [ ] 6. Run \`yg drift-sync\` for affected nodes
 
-When mapping a file, execute this mental routing:
+### Reverse Engineering
 
-### Layer 1: Unit Identity (Local Node Artifacts)
-* **What goes here:** Things exclusively true for this specific node.
-* **Routing:** **DO NOT ASSUME FILE NAMES.** You MUST read \`.yggdrasil/config.yaml\` (the \`artifacts\` section) to see the exact allowed filenames for the current project and their requirement conditions (e.g., \`required: always\` vs \`when: has_incoming_relations\`). Write local node knowledge ONLY into these configured files next to \`node.yaml\`.
-* For each artifact in \`config.artifacts\`, use its \`description\` to decide what content belongs there. Create optional artifacts (those with \`required: never\`) when the node has matching content. Extract from source; do not invent.
+**Order:** aspects (cross-cutting patterns) \u2192 flows (business processes) \u2192 model nodes. Never create nodes before aspects and flows are understood.
 
-**Subagents:** When mapping a node, for each optional artifact in config, ask: "Does the source contain content matching this artifact's description?" If yes, create it. Do not invent \u2014 extract only what is implemented.
+Per area checklist:
 
-### Optional Artifacts \u2014 Explicit Consideration
+- [ ] 1. \`yg owner --file <path>\` \u2014 confirm no coverage
+- [ ] 2. Determine node granularity \u2014 propose to user if unclear
+- [ ] 3. Create node directory, read \`schemas/node.yaml\`, create \`node.yaml\`
+- [ ] 4. Analyze source \u2014 for each artifact type in \`config.artifacts\`: extract content, do not invent
+- [ ] 5. Identify relations \u2014 add to \`node.yaml\`
+- [ ] 6. Identify cross-cutting requirements \u2014 add matching aspects, create if needed
+- [ ] 7. Identify business process participation \u2014 add to flow, ask user if process unclear
+- [ ] 8. \`yg validate\` \u2014 fix errors
+- [ ] 9. \`yg drift-sync --node <path>\`
 
-When creating or editing a graph node, or mapping source files to a node, after fulfilling required artifacts, read \`config.yaml\` and for each artifact with \`required: never\`, ask: "Does this node contain content that matches this artifact's description?" If yes, create it. Base decisions on source code analysis, not file names or structure.
+**When to ask:**
 
-**Interpretation of \`required: never\`:** The artifact is optional for validation, not forbidden. Create it when the node has content that fits its description in config.
+- Business process unclear: "This code appears to be part of a larger process. Can you describe what it means from a business perspective?"
+- Constraint without rationale: "I see [constraint X]. Do you know why this exists? I want to record the reason, not just the rule."
+- Unexplained architectural choice: "I see [approach X]. What was the reason for this choice?"
+- Decision without alternatives: "You chose [X]. What alternatives did you consider, and why did you reject them?" Record the answer in \`decisions.md\`.
 
-**Interpretation of "don't be over-eager":** Do not invent content, do not document what is not in the code, do not create empty or trivial artifacts. It does NOT mean: avoid adding optional artifacts when they add value based on code analysis.
+### Bootstrap Mode
 
-**Post-node checklist:** After completing work on a node, for each optional artifact (from \`config.artifacts\` where \`required: never\`), check: does this node have content for it? If yes, create it. If uncertain, propose with brief justification rather than silently skipping.
+Trigger: \`yg preflight\` shows 0 nodes, or no nodes cover the active work area.
 
-### Layer 2: Surroundings (Relations & Flows)
-* **What goes here:** How this node interacts with others. You must not duplicate external interfaces locally.
-* **Routing:**
-  * If it calls another module: Add an outgoing structural \`relation\` in \`node.yaml\`. (The engine will automatically fetch the target's structural-context artifacts: responsibility, interface, constraints, errors).
-  * If it participates in an end-to-end process: Do not explain the whole process locally. Ensure the node is listed in \`.yggdrasil/flows/<flow_name>/flow.yaml\`. The engine will attach the flow knowledge automatically.
-* **Flows \u2014 writing flow content:** When creating or editing flow artifacts (e.g. \`description.md\` in \`flows/<name>/\`), write business-first: describe the process from user/business perspective. Technical details only as inserts when they clarify the flow. Not technical-first with business inserts.
+- [ ] 1. Identify the active work area (files the user wants to modify)
+- [ ] 2. Scan for cross-cutting patterns \u2192 create aspects
+- [ ] 3. Ask user about business processes \u2192 create flows if applicable
+- [ ] 4. Propose node structure for the area
+- [ ] 5. Create node(s) with initial artifacts, map files
+- [ ] 6. \`yg validate\`, \`yg drift-sync\`
+- [ ] 7. Proceed with user's original request
 
-### Layer 3: Domain Context (Hierarchy)
-* **What goes here:** Business rules shared by a family of nodes.
-* **Routing:** Do not repeat module-wide rules in every child node. Place the child node directory *inside* a parent Module Node directory. Write the shared rules in the parent's configured artifacts. The engine inherently passes parent context to children.
+Constraint: Do NOT map the entire repository. Focus on the active area. Expand incrementally.
 
-### Layer 4: Cross-Cutting Rules (Aspects)
-* **What goes here:** Horizontal requirements like logging, auth, rate-limiting, or specific frameworks.
-* **Routing:** Do NOT write generic rules like "This node must log all errors" in local artifacts. Instead, read \`config.yaml\` for available \`tags\`. Add the relevant tag (e.g., \`requires-audit\`) to \`node.yaml\`. The engine will automatically attach the aspect knowledge.
+### Drift Resolution
 
-### Layer 5: Long-Term Memory (Knowledge Elements)
-* **What goes here:** Global architectural decisions, design patterns, and systemic invariants.
-* **Routing:** Read \`config.yaml\` (the \`knowledge_categories\` section) to know what categories exist.
-  * If the file implements a standard pattern: Do not describe the pattern locally. Add a \`knowledge\` reference in \`node.yaml\` to the existing pattern.
-  * If the file reveals an undocumented global invariant or decision: Ask the user to confirm it. If confirmed, create it under \`.yggdrasil/knowledge/<category>/\` so all future nodes inherit it.
+Always ask the user before resolving drift. Never auto-resolve.
 
-**THE COMPLETENESS CHECK:**
-Before finishing a mapping, ask yourself: *"If I delete the source file and give another agent ONLY the output of \`yg build-context\`, can they recreate it perfectly based on the configured artifacts, AND will they understand EXACTLY WHY this code exists and why it was designed this way?"*
-- If no -> You missed a local constraint, a relation, or you failed to capture the user's provided rationale.
-- If yes, but the local files are bloated -> You failed to deconstruct knowledge into Tags, Aspects, Flows, and Hierarchy. Fix the routing.
+- **Source drift** (source files changed) \u2192 update graph artifacts to match source, then \`yg drift-sync\`
+- **Graph drift** (graph artifacts changed) \u2192 review affected source, update if needed, then \`yg drift-sync\`
+- **Full drift** (both changed) \u2192 present both sides to user, ask which direction wins
+- **Missing** \u2192 ask: re-materialize or remove mapping?
+- **Unmaterialized** \u2192 ask user how to proceed
 
----
+Threshold: >10 drifted nodes \u2192 ask user which area to prioritize. Do not resolve all at once.
 
-## 8. CLI TOOLS REFERENCE (\`yg\`)
+### Error Recovery
 
-Always use these exact commands.
+- **\`yg\` not found** \u2192 inform user: "yg CLI is not installed or not in PATH." Stop.
+- **Unfixable validate errors** \u2192 if not resolved after 3 attempts, stop and report to user. Do not loop.
+- **Budget exceeded** \u2192 if \`yg build-context\` exits with error (context package exceeds budget), warn user: "This node should be split." Do not proceed with implementation.
+- **Corrupted \`.yggdrasil/\` files** \u2192 report to user. Do not attempt repair.
+- **Incremental sync** \u2192 run \`yg drift-sync\` every 3-5 source files during multi-file tasks. Do not defer to end.`;
+var KNOWLEDGE_BASE = `## KNOWLEDGE BASE
 
-* \`yg owner --file <file_path>\` -> Find owning node.
-* \`yg build-context --node <node_path>\` -> Assemble strict specification.
-* \`yg tree [--root <node_path>] [--depth N]\` -> Print graph structure.
-* \`yg deps --node <node_path> [--type structural|event|all]\` -> Show dependencies.
-* \`yg impact --node <node_path> --simulate\` -> Simulate blast radius.
-* \`yg status\` -> Graph health metrics.
-* \`yg validate [--scope <node_path>|all]\` -> Compile/check graph. Run after EVERY graph edit.
-* \`yg drift [--scope <node_path>|all]\` -> Check code vs graph baseline.
-* \`yg drift-sync --node <node_path>\` -> Save current file hash as new baseline. Run ONLY after ensuring graph artifacts match the code.
+### Graph Structure
 
-*(Iterative mode only)*
-* \`yg journal-read\`
-* \`yg journal-add --note "<content>" [--target <node_path>]\`
-* \`yg journal-archive\`
+\`\`\`
+.yggdrasil/
+  config.yaml        \u2190 vocabulary, stack, node types, artifact rules, required aspects
+  model/             \u2190 what exists: nodes, hierarchy, relations, file mappings
+  aspects/           \u2190 what must: cross-cutting requirements with rationale and guidance
+  flows/             \u2190 why and in what process: business processes with node participation
+  schemas/           \u2190 YAML schemas \u2014 read before creating any graph element
+  .drift-state       \u2190 generated by CLI; never edit manually
+  .journal.yaml      \u2190 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 \u2014 use \`implies\` explicitly.
+- **Flows = business processes.** A flow describes what happens in the world, not code sequences. Flow aspects propagate to all participants.
+
+### Context Assembly
+
+Run \`yg build-context --node <path>\` to get the deterministic context package for a node. Trust the package \u2014 it assembles global config, hierarchy, own artifacts, aspects, and relational context. If the package is insufficient, enrich the graph. Do not bypass it with raw file exploration.
+
+### Information Routing
+
+When you encounter information, route it to the correct location:
+
+- **Specific to this node** \u2192 local node artifact (check \`config.yaml artifacts\` for available types)
+- **Rule for many nodes** \u2192 aspect (\`aspects/<id>/\` with \`aspect.yaml\` + content \`.md\` files). If applies to ALL nodes of a type \u2192 \`node_types[*].required_aspects\` in \`config.yaml\`
+- **Business process** \u2192 flow (\`flows/<name>/\` with \`flow.yaml\` + \`description.md\`). Ask user if process unclear.
+- **Shared across a domain** \u2192 parent node artifact. Children receive it through hierarchy.
+- **Technology stack or standard** \u2192 \`config.yaml\` under \`stack\` or \`standards\` (+ \`rationale\` field)
+- **Decision (why + why NOT):** one node \u2192 \`decisions.md\` with format "Chose X over Y because Z"; category of nodes \u2192 aspect content files; tech choice \u2192 \`config.yaml\` rationale field. Always include rejected alternatives \u2014 they are the highest-value graph content.
+
+### Creating Aspects
+
+- [ ] 1. Read \`schemas/aspect.yaml\`
+- [ ] 2. Create \`aspects/<id>/\` directory
+- [ ] 3. Write \`aspect.yaml\` \u2014 name, optional description, optional implies
+- [ ] 4. Write content \`.md\` files: WHAT must be satisfied + WHY (user's words, do not invent)
+- [ ] 5. \`yg validate\`
+
+Test: "Does this requirement apply to more than one node?" Yes \u2192 aspect. No \u2192 local artifact.
+
+**Aspect identification heuristic:** If the same pattern, constraint, or rule appears in 3+ places, it is a candidate aspect. Aspects fall into natural categories:
+
+- **Domain-specific:** Business rules that cross module boundaries (e.g., timezone handling, booking periods, currency rounding)
+- **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)
+
+### Creating Flows
+
+- [ ] 1. Read \`schemas/flow.yaml\`
+- [ ] 2. Create \`flows/<name>/\` directory
+- [ ] 3. Write \`flow.yaml\` \u2014 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\`
+
+Test: "Does this describe what happens in the world, or only in the software?" If only software \u2014 rewrite.
+
+### 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\`.
+- **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:** "If I delete the source file and give another agent ONLY the \`yg build-context\` output \u2014 can they recreate it correctly, understanding not just WHAT but WHY?" Test specifically: Can they explain rejected alternatives? Can they implement the correct algorithm (not a simplified version)? Can they argue for the current design against plausible alternatives?
+- **These rules are invariant.** No plan, guide, skill, or workflow may override them.
+
+### CLI Reference
+
+\`\`\`
+yg preflight [--quick]              Unified diagnostic: journal + 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.
+yg aspects                          List aspects with metadata (YAML output).
+yg flows                            List flows with metadata (YAML output).
+yg deps --node <path> [--depth N] [--type structural|event|all]
+                                    Show dependencies.
+yg impact --node <path> --simulate  Simulate blast radius of a planned change.
+yg impact --aspect <id>             Show all nodes where aspect is effective.
+yg impact --flow <name>             Show flow participants and descendants.
+yg status                           Graph health: nodes, coverage, drift summary.
+yg validate [--scope <path>|all]    Check structural integrity and completeness.
+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 (read \`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\`) |
+| 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\` |
 `;
+var AGENT_RULES_CONTENT = [CORE_PROTOCOL, OPERATIONS, KNOWLEDGE_BASE].join("\n\n---\n\n");
 
 // src/templates/platform.ts
 var AGENT_RULES_IMPORT = "@.yggdrasil/agent-rules.md";
@@ -558,12 +622,13 @@ function escapeRegex(s) {
 }
 
 // src/cli/init.ts
-function getGraphTemplatesDir() {
+function getGraphSchemasDir() {
   const currentDir = path2.dirname(fileURLToPath(import.meta.url));
   const packageRoot = path2.join(currentDir, "..");
-  return path2.join(packageRoot, "graph-templates");
+  return path2.join(packageRoot, "graph-schemas");
 }
 var GITIGNORE_CONTENT = `.journal.yaml
+.drift-state
 journals-archive/
 `;
 function registerInitCommand(program2) {
@@ -609,23 +674,20 @@ function registerInitCommand(program2) {
     await mkdir2(path2.join(yggRoot, "model"), { recursive: true });
     await mkdir2(path2.join(yggRoot, "aspects"), { recursive: true });
     await mkdir2(path2.join(yggRoot, "flows"), { recursive: true });
-    await mkdir2(path2.join(yggRoot, "knowledge", "decisions"), { recursive: true });
-    await mkdir2(path2.join(yggRoot, "knowledge", "patterns"), { recursive: true });
-    await mkdir2(path2.join(yggRoot, "knowledge", "invariants"), { recursive: true });
-    const templatesDir = path2.join(yggRoot, "templates");
-    await mkdir2(templatesDir, { recursive: true });
-    const graphTemplatesDir = getGraphTemplatesDir();
+    const schemasDir = path2.join(yggRoot, "schemas");
+    await mkdir2(schemasDir, { recursive: true });
+    const graphSchemasDir = getGraphSchemasDir();
     try {
-      const entries = await readdir(graphTemplatesDir, { withFileTypes: true });
-      const templateFiles = entries.filter((e) => e.isFile()).map((e) => e.name);
-      for (const file of templateFiles) {
-        const srcPath = path2.join(graphTemplatesDir, file);
+      const entries = await readdir(graphSchemasDir, { withFileTypes: true });
+      const schemaFiles = entries.filter((e) => e.isFile()).map((e) => e.name);
+      for (const file of schemaFiles) {
+        const srcPath = path2.join(graphSchemasDir, file);
         const content = await readFile2(srcPath, "utf-8");
-        await writeFile2(path2.join(templatesDir, file), content, "utf-8");
+        await writeFile2(path2.join(schemasDir, file), content, "utf-8");
       }
     } catch (err) {
       process.stderr.write(
-        `Warning: Could not copy graph templates from ${graphTemplatesDir}: ${err.message}
+        `Warning: Could not copy graph schemas from ${graphSchemasDir}: ${err.message}
 `
       );
     }
@@ -639,10 +701,7 @@ function registerInitCommand(program2) {
     process.stdout.write("  .yggdrasil/model/\n");
     process.stdout.write("  .yggdrasil/aspects/\n");
     process.stdout.write("  .yggdrasil/flows/\n");
-    process.stdout.write("  .yggdrasil/knowledge/ (decisions, patterns, invariants)\n");
-    process.stdout.write(
-      "  .yggdrasil/templates/ (node, aspect, flow, knowledge)\n"
-    );
+    process.stdout.write("  .yggdrasil/schemas/ (config, node, aspect, flow)\n");
     process.stdout.write(`  ${path2.relative(projectRoot, rulesPath)} (rules)
 
 `);
@@ -654,8 +713,8 @@ function registerInitCommand(program2) {
 }
 
 // src/core/graph-loader.ts
-import { readdir as readdir3 } from "fs/promises";
-import path6 from "path";
+import { readdir as readdir3, readFile as readFile9 } from "fs/promises";
+import path7 from "path";
 
 // src/io/config-parser.ts
 import { readFile as readFile3 } from "fs/promises";
@@ -663,27 +722,45 @@ import { parse as parseYaml } from "yaml";
 var DEFAULT_QUALITY = {
   min_artifact_length: 50,
   max_direct_relations: 10,
-  context_budget: { warning: 1e4, error: 2e4 },
-  knowledge_staleness_days: 90
+  context_budget: { warning: 1e4, error: 2e4 }
 };
 async function parseConfig(filePath) {
   const content = await readFile3(filePath, "utf-8");
   const raw = parseYaml(content);
+  if (!raw || typeof raw !== "object") {
+    throw new Error(`config.yaml: file is empty or not a valid YAML mapping`);
+  }
   if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
     throw new Error(`config.yaml: missing or invalid 'name' field`);
   }
-  const nodeTypes = raw.node_types;
-  if (!Array.isArray(nodeTypes) || nodeTypes.length === 0) {
+  const nodeTypesRaw = raw.node_types;
+  if (!Array.isArray(nodeTypesRaw) || nodeTypesRaw.length === 0) {
     throw new Error(`config.yaml: 'node_types' must be a non-empty array`);
   }
+  const nodeTypes = nodeTypesRaw.map((item) => {
+    if (typeof item === "string") {
+      return { name: item };
+    }
+    if (typeof item === "object" && item !== null && "name" in item && typeof item.name === "string") {
+      const obj = item;
+      const requiredAspects = Array.isArray(obj.required_aspects) ? obj.required_aspects.filter((t) => typeof t === "string") : Array.isArray(obj.required_tags) ? obj.required_tags.filter((t) => typeof t === "string") : void 0;
+      return {
+        name: obj.name,
+        required_aspects: requiredAspects && requiredAspects.length > 0 ? requiredAspects : void 0
+      };
+    }
+    throw new Error(
+      `config.yaml: node_types entry must be string or { name, required_aspects? }`
+    );
+  });
   const artifacts = raw.artifacts;
   if (!artifacts || typeof artifacts !== "object" || Array.isArray(artifacts) || Object.keys(artifacts).length === 0) {
     throw new Error(`config.yaml: 'artifacts' must be a non-empty object`);
   }
   const artifactsMap = {};
   for (const [key, val] of Object.entries(artifacts)) {
-    if (key === "node") {
-      throw new Error(`config.yaml: artifact name 'node' is reserved`);
+    if (key === "node.yaml") {
+      throw new Error(`config.yaml: artifact name 'node.yaml' is reserved`);
     }
     const a = val;
     const required = a.required;
@@ -692,10 +769,10 @@ async function parseConfig(filePath) {
     }
     if (typeof required === "object" && required && "when" in required) {
       const when = required.when;
-      const validWhen = when === "has_incoming_relations" || when === "has_outgoing_relations" || typeof when === "string" && when.startsWith("has_tag:");
+      const validWhen = when === "has_incoming_relations" || when === "has_outgoing_relations" || typeof when === "string" && (when.startsWith("has_aspect:") || when.startsWith("has_tag:"));
       if (!validWhen) {
         throw new Error(
-          `config.yaml: artifact '${key}' has invalid 'required.when': must be has_incoming_relations, has_outgoing_relations, or has_tag:<name>`
+          `config.yaml: artifact '${key}' has invalid 'required.when': must be has_incoming_relations, has_outgoing_relations, or has_aspect:<name>`
         );
       }
     }
@@ -705,24 +782,6 @@ async function parseConfig(filePath) {
       structural_context: a.structural_context ?? false
     };
   }
-  if (!("knowledge_categories" in raw)) {
-    throw new Error(
-      `config.yaml: missing 'knowledge_categories' field (required, may be empty list)`
-    );
-  }
-  const knowledgeCategoriesRaw = raw.knowledge_categories;
-  if (!Array.isArray(knowledgeCategoriesRaw)) {
-    throw new Error(`config.yaml: 'knowledge_categories' must be an array`);
-  }
-  const knowledgeCategories = knowledgeCategoriesRaw;
-  const categoryNames = /* @__PURE__ */ new Set();
-  for (const kc of knowledgeCategories) {
-    if (!kc?.name || typeof kc.name !== "string") continue;
-    if (categoryNames.has(kc.name)) {
-      throw new Error(`config.yaml: duplicate knowledge category '${kc.name}'`);
-    }
-    categoryNames.add(kc.name);
-  }
   const qualityRaw = raw.quality;
   const quality = qualityRaw ? {
     min_artifact_length: qualityRaw.min_artifact_length ?? DEFAULT_QUALITY.min_artifact_length,
@@ -730,30 +789,19 @@ async function parseConfig(filePath) {
     context_budget: {
       warning: qualityRaw.context_budget?.warning ?? DEFAULT_QUALITY.context_budget.warning,
       error: qualityRaw.context_budget?.error ?? DEFAULT_QUALITY.context_budget.error
-    },
-    knowledge_staleness_days: qualityRaw.knowledge_staleness_days ?? DEFAULT_QUALITY.knowledge_staleness_days
+    }
   } : DEFAULT_QUALITY;
   if (quality.context_budget.error < quality.context_budget.warning) {
     throw new Error(
       `config.yaml: quality.context_budget.error (${quality.context_budget.error}) must be >= warning (${quality.context_budget.warning})`
     );
   }
-  if (!("tags" in raw)) {
-    throw new Error(`config.yaml: missing 'tags' field (required, may be empty list)`);
-  }
-  const tags = raw.tags;
-  if (!Array.isArray(tags)) {
-    throw new Error(`config.yaml: 'tags' must be an array`);
-  }
-  const tagsList = tags.filter((t) => typeof t === "string");
   return {
     name: raw.name.trim(),
     stack: raw.stack ?? {},
     standards: typeof raw.standards === "string" ? raw.standards : "",
-    tags: tagsList,
     node_types: nodeTypes,
     artifacts: artifactsMap,
-    knowledge_categories: knowledgeCategories.filter((kc) => kc?.name),
     quality
   };
 }
@@ -775,6 +823,9 @@ function isValidRelationType(t) {
 async function parseNodeYaml(filePath) {
   const content = await readFile4(filePath, "utf-8");
   const raw = parseYaml2(content);
+  if (!raw || typeof raw !== "object") {
+    throw new Error(`node.yaml at ${filePath}: file is empty or not a valid YAML mapping`);
+  }
   if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
     throw new Error(`node.yaml at ${filePath}: missing or empty 'name'`);
   }
@@ -786,10 +837,9 @@ async function parseNodeYaml(filePath) {
   return {
     name: raw.name.trim(),
     type: raw.type.trim(),
-    tags: parseStringArray(raw.tags),
+    aspects: parseStringArray(raw.aspects) ?? parseStringArray(raw.tags),
     blackbox: raw.blackbox ?? false,
     relations: relations.length > 0 ? relations : void 0,
-    knowledge: parseStringArray(raw.knowledge),
     mapping
   };
 }
@@ -889,29 +939,47 @@ async function readArtifacts(dirPath, excludeFiles = ["node.yaml"], includeFiles
 }
 
 // src/io/aspect-parser.ts
-async function parseAspect(aspectDir, aspectYamlPath) {
+async function parseAspect(aspectDir, aspectYamlPath, id) {
+  const idTrimmed = id?.trim() ?? "";
+  if (!idTrimmed) {
+    throw new Error(`Aspect id must be non-empty (relative path in aspects/)`);
+  }
   const content = await readFile6(aspectYamlPath, "utf-8");
   const raw = parseYaml3(content);
+  if (!raw || typeof raw !== "object") {
+    throw new Error(`Aspect file ${aspectYamlPath}: file is empty or not a valid YAML mapping`);
+  }
   if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
     throw new Error(`Aspect file ${aspectYamlPath}: missing or empty 'name'`);
   }
-  if (!raw.tag || typeof raw.tag !== "string" || raw.tag.trim() === "") {
-    throw new Error(`Aspect file ${aspectYamlPath}: missing or empty 'tag'`);
-  }
+  const description = typeof raw.description === "string" ? raw.description.trim() : void 0;
   const artifacts = await readArtifacts(aspectDir, ["aspect.yaml"]);
+  let implies;
+  if (raw.implies !== void 0) {
+    if (!Array.isArray(raw.implies)) {
+      throw new Error(`Aspect file ${aspectYamlPath}: 'implies' must be an array of strings`);
+    }
+    implies = raw.implies.filter((t) => typeof t === "string");
+  }
   return {
     name: raw.name.trim(),
-    tag: raw.tag.trim(),
+    id: idTrimmed,
+    description,
+    implies,
     artifacts
   };
 }
 
 // src/io/flow-parser.ts
 import { readFile as readFile7 } from "fs/promises";
+import path4 from "path";
 import { parse as parseYaml4 } from "yaml";
 async function parseFlow(flowDir, flowYamlPath) {
   const content = await readFile7(flowYamlPath, "utf-8");
   const raw = parseYaml4(content);
+  if (!raw || typeof raw !== "object") {
+    throw new Error(`flow.yaml at ${flowYamlPath}: file is empty or not a valid YAML mapping`);
+  }
   if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
     throw new Error(`flow.yaml at ${flowYamlPath}: missing or empty 'name'`);
   }
@@ -923,79 +991,44 @@ async function parseFlow(flowDir, flowYamlPath) {
   if (nodePaths.length === 0) {
     throw new Error(`flow.yaml at ${flowYamlPath}: 'nodes' must contain string node paths`);
   }
-  const knowledge = Array.isArray(raw.knowledge) ? raw.knowledge.filter((k) => typeof k === "string") : void 0;
+  let aspects;
+  if (raw.aspects !== void 0) {
+    if (!Array.isArray(raw.aspects)) {
+      throw new Error(`flow.yaml at ${flowYamlPath}: 'aspects' must be an array of strings`);
+    }
+    const aspectTags = raw.aspects.filter((a) => typeof a === "string");
+    aspects = aspectTags.length > 0 ? aspectTags : [];
+  }
   const artifacts = await readArtifacts(flowDir, ["flow.yaml"]);
   return {
+    path: path4.basename(flowDir),
     name: raw.name.trim(),
     nodes: nodePaths,
-    knowledge,
+    ...aspects !== void 0 && { aspects },
     artifacts
   };
 }
 
-// src/io/knowledge-parser.ts
+// src/io/schema-parser.ts
 import { readFile as readFile8 } from "fs/promises";
+import path5 from "path";
 import { parse as parseYaml5 } from "yaml";
-async function parseKnowledge(knowledgeDir, knowledgeYamlPath, category, relativePath) {
-  const content = await readFile8(knowledgeYamlPath, "utf-8");
-  const raw = parseYaml5(content);
-  if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
-    throw new Error(`knowledge.yaml at ${knowledgeYamlPath}: missing or empty 'name'`);
-  }
-  const scope = parseScope(raw.scope, knowledgeYamlPath);
-  const artifacts = await readArtifacts(knowledgeDir, ["knowledge.yaml"]);
-  return {
-    name: raw.name.trim(),
-    scope,
-    category,
-    path: relativePath,
-    artifacts
-  };
-}
-function parseScope(raw, filePath) {
-  if (raw === "global") {
-    return "global";
-  }
-  if (raw && typeof raw === "object") {
-    const obj = raw;
-    if (Array.isArray(obj.tags)) {
-      const tags = obj.tags.filter((t) => typeof t === "string");
-      if (tags.length === 0) {
-        throw new Error(`knowledge.yaml at ${filePath}: scope.tags must be a non-empty array`);
-      }
-      return { tags };
-    }
-    if (Array.isArray(obj.nodes)) {
-      const nodes = obj.nodes.filter((n) => typeof n === "string");
-      if (nodes.length === 0) {
-        throw new Error(`knowledge.yaml at ${filePath}: scope.nodes must be a non-empty array`);
-      }
-      return { nodes };
-    }
-  }
-  throw new Error(`knowledge.yaml at ${filePath}: invalid 'scope' value`);
-}
-
-// src/io/template-parser.ts
-import { readFile as readFile9 } from "fs/promises";
-import path4 from "path";
-import { parse as parseYaml6 } from "yaml";
 async function parseSchema(filePath) {
-  const content = await readFile9(filePath, "utf-8");
-  parseYaml6(content);
-  const schemaType = path4.basename(filePath, path4.extname(filePath));
+  const content = await readFile8(filePath, "utf-8");
+  parseYaml5(content);
+  const schemaType = path5.basename(filePath, path5.extname(filePath));
   return { schemaType };
 }
 
 // src/utils/paths.ts
-import path5 from "path";
+import path6 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { stat as stat2 } from "fs/promises";
 async function findYggRoot(projectRoot) {
-  let current = path5.resolve(projectRoot);
-  const root = path5.parse(current).root;
+  let current = path6.resolve(projectRoot);
+  const root = path6.parse(current).root;
   while (true) {
-    const yggPath = path5.join(current, ".yggdrasil");
+    const yggPath = path6.join(current, ".yggdrasil");
     try {
       const st = await stat2(yggPath);
       if (!st.isDirectory()) {
@@ -1009,7 +1042,7 @@ async function findYggRoot(projectRoot) {
         if (current === root) {
           throw new Error(`No .yggdrasil/ directory found. Run 'yg init' first.`, { cause: err });
         }
-        current = path5.dirname(current);
+        current = path6.dirname(current);
         continue;
       }
       throw err;
@@ -1025,41 +1058,42 @@ function normalizeProjectRelativePath(projectRoot, rawPath) {
   if (normalizedInput.length === 0) {
     throw new Error("Path cannot be empty");
   }
-  const absolute = path5.resolve(projectRoot, normalizedInput);
-  const relative = path5.relative(projectRoot, absolute);
-  const isOutside = relative.startsWith("..") || path5.isAbsolute(relative);
+  const absolute = path6.resolve(projectRoot, normalizedInput);
+  const relative = path6.relative(projectRoot, absolute);
+  const isOutside = relative.startsWith("..") || path6.isAbsolute(relative);
   if (isOutside) {
     throw new Error(`Path is outside project root: ${rawPath}`);
   }
-  return relative.split(path5.sep).join("/");
+  return relative.split(path6.sep).join("/");
+}
+function projectRootFromGraph(yggRootPath) {
+  return path6.dirname(yggRootPath);
 }
 
 // src/core/graph-loader.ts
 function toModelPath(absolutePath, modelDir) {
-  return path6.relative(modelDir, absolutePath).split(path6.sep).join("/");
+  return path7.relative(modelDir, absolutePath).split(path7.sep).join("/");
 }
 var FALLBACK_CONFIG = {
   name: "",
   stack: {},
   standards: "",
-  tags: [],
   node_types: [],
-  artifacts: {},
-  knowledge_categories: []
+  artifacts: {}
 };
 async function loadGraph(projectRoot, options = {}) {
   const yggRoot = await findYggRoot(projectRoot);
   let configError;
   let config = FALLBACK_CONFIG;
   try {
-    config = await parseConfig(path6.join(yggRoot, "config.yaml"));
+    config = await parseConfig(path7.join(yggRoot, "config.yaml"));
   } catch (error) {
     if (!options.tolerateInvalidConfig) {
       throw error;
     }
     configError = error.message;
   }
-  const modelDir = path6.join(yggRoot, "model");
+  const modelDir = path7.join(yggRoot, "model");
   const nodes = /* @__PURE__ */ new Map();
   const nodeParseErrors = [];
   const artifactFilenames = Object.keys(config.artifacts ?? {});
@@ -1073,13 +1107,9 @@ async function loadGraph(projectRoot, options = {}) {
     }
     throw err;
   }
-  const aspects = await loadAspects(path6.join(yggRoot, "aspects"));
-  const flows = await loadFlows(path6.join(yggRoot, "flows"));
-  const knowledge = await loadKnowledge(
-    path6.join(yggRoot, "knowledge"),
-    config.knowledge_categories
-  );
-  const schemas = await loadSchemas(path6.join(yggRoot, "templates"));
+  const aspects = await loadAspects(path7.join(yggRoot, "aspects"));
+  const flows = await loadFlows(path7.join(yggRoot, "flows"));
+  const schemas = await loadSchemas(path7.join(yggRoot, "schemas"));
   return {
     config,
     configError,
@@ -1087,7 +1117,6 @@ async function loadGraph(projectRoot, options = {}) {
     nodes,
     aspects,
     flows,
-    knowledge,
     schemas,
     rootPath: yggRoot
   };
@@ -1100,9 +1129,12 @@ async function scanModelDirectory(dirPath, modelDir, parent, nodes, nodeParseErr
   }
   if (hasNodeYaml) {
     const graphPath = toModelPath(dirPath, modelDir);
+    const nodeYamlPath = path7.join(dirPath, "node.yaml");
     let meta;
+    let nodeYamlRaw;
     try {
-      meta = await parseNodeYaml(path6.join(dirPath, "node.yaml"));
+      nodeYamlRaw = await readFile9(nodeYamlPath, "utf-8");
+      meta = await parseNodeYaml(nodeYamlPath);
     } catch (err) {
       nodeParseErrors.push({
         nodePath: graphPath,
@@ -1114,6 +1146,7 @@ async function scanModelDirectory(dirPath, modelDir, parent, nodes, nodeParseErr
     const node = {
       path: graphPath,
       meta,
+      nodeYamlRaw,
       artifacts,
       children: [],
       parent
@@ -1126,7 +1159,7 @@ async function scanModelDirectory(dirPath, modelDir, parent, nodes, nodeParseErr
       if (!entry.isDirectory()) continue;
       if (entry.name.startsWith(".")) continue;
       await scanModelDirectory(
-        path6.join(dirPath, entry.name),
+        path7.join(dirPath, entry.name),
         modelDir,
         node,
         nodes,
@@ -1139,7 +1172,7 @@ async function scanModelDirectory(dirPath, modelDir, parent, nodes, nodeParseErr
       if (!entry.isDirectory()) continue;
       if (entry.name.startsWith(".")) continue;
       await scanModelDirectory(
-        path6.join(dirPath, entry.name),
+        path7.join(dirPath, entry.name),
         modelDir,
         null,
         nodes,
@@ -1151,27 +1184,36 @@ async function scanModelDirectory(dirPath, modelDir, parent, nodes, nodeParseErr
 }
 async function loadAspects(aspectsDir) {
   try {
-    const entries = await readdir3(aspectsDir, { withFileTypes: true });
     const aspects = [];
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const aspectYamlPath = path6.join(aspectsDir, entry.name, "aspect.yaml");
-      const aspect = await parseAspect(path6.join(aspectsDir, entry.name), aspectYamlPath);
-      aspects.push(aspect);
-    }
+    await scanAspectsDirectory(aspectsDir, aspectsDir, aspects);
     return aspects;
   } catch {
     return [];
   }
 }
+async function scanAspectsDirectory(dirPath, aspectsRoot, aspects) {
+  const entries = await readdir3(dirPath, { withFileTypes: true });
+  const hasAspectYaml = entries.some((e) => e.isFile() && e.name === "aspect.yaml");
+  if (hasAspectYaml) {
+    const id = path7.relative(aspectsRoot, dirPath).split(path7.sep).join("/");
+    const aspectYamlPath = path7.join(dirPath, "aspect.yaml");
+    const aspect = await parseAspect(dirPath, aspectYamlPath, id);
+    aspects.push(aspect);
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith(".")) continue;
+    await scanAspectsDirectory(path7.join(dirPath, entry.name), aspectsRoot, aspects);
+  }
+}
 async function loadFlows(flowsDir) {
   try {
     const entries = await readdir3(flowsDir, { withFileTypes: true });
     const flows = [];
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      const flowYamlPath = path6.join(flowsDir, entry.name, "flow.yaml");
-      const flow = await parseFlow(path6.join(flowsDir, entry.name), flowYamlPath);
+      const flowYamlPath = path7.join(flowsDir, entry.name, "flow.yaml");
+      const flow = await parseFlow(path7.join(flowsDir, entry.name), flowYamlPath);
       flows.push(flow);
     }
     return flows;
@@ -1179,37 +1221,14 @@ async function loadFlows(flowsDir) {
     return [];
   }
 }
-async function loadKnowledge(knowledgeDir, categories) {
-  const items = [];
-  const categorySet = new Set(categories.map((c) => c.name));
-  try {
-    const catEntries = await readdir3(knowledgeDir, { withFileTypes: true });
-    for (const catEntry of catEntries) {
-      if (!catEntry.isDirectory()) continue;
-      if (!categorySet.has(catEntry.name)) continue;
-      const catPath = path6.join(knowledgeDir, catEntry.name);
-      const itemEntries = await readdir3(catPath, { withFileTypes: true });
-      for (const itemEntry of itemEntries) {
-        if (!itemEntry.isDirectory()) continue;
-        const itemDir = path6.join(catPath, itemEntry.name);
-        const knowledgeYamlPath = path6.join(itemDir, "knowledge.yaml");
-        const relativePath = `${catEntry.name}/${itemEntry.name}`;
-        const item = await parseKnowledge(itemDir, knowledgeYamlPath, catEntry.name, relativePath);
-        items.push(item);
-      }
-    }
-  } catch {
-  }
-  return items;
-}
-async function loadSchemas(templatesDir) {
+async function loadSchemas(schemasDir) {
   try {
-    const entries = await readdir3(templatesDir, { withFileTypes: true });
+    const entries = await readdir3(schemasDir, { withFileTypes: true });
     const schemas = [];
     for (const entry of entries) {
       if (!entry.isFile()) continue;
       if (!entry.name.endsWith(".yaml") && !entry.name.endsWith(".yml")) continue;
-      const s = await parseSchema(path6.join(templatesDir, entry.name));
+      const s = await parseSchema(path7.join(schemasDir, entry.name));
       schemas.push(s);
     }
     return schemas;
@@ -1220,7 +1239,7 @@ async function loadSchemas(templatesDir) {
 
 // src/core/context-builder.ts
 import { readFile as readFile10 } from "fs/promises";
-import path7 from "path";
+import path8 from "path";
 
 // src/utils/tokens.ts
 function estimateTokens(text) {
@@ -1235,47 +1254,42 @@ async function buildContext(graph, nodePath) {
   if (!node) {
     throw new Error(`Node not found: ${nodePath}`);
   }
-  const nodeTags = new Set(node.meta.tags ?? []);
-  const seenKnowledge = /* @__PURE__ */ new Set();
   const layers = [];
   layers.push(buildGlobalLayer(graph.config));
-  for (const k of collectKnowledgeItems(graph, nodePath, nodeTags, seenKnowledge)) {
-    layers.push(buildKnowledgeLayer(k));
-  }
   const ancestors = collectAncestors(node);
   for (const ancestor of ancestors) {
-    layers.push(buildHierarchyLayer(ancestor, graph.config));
+    layers.push(buildHierarchyLayer(ancestor, graph.config, graph));
   }
-  layers.push(await buildOwnLayer(node, graph.config, graph.rootPath));
+  layers.push(await buildOwnLayer(node, graph.config, graph.rootPath, graph));
+  const ancestorPaths = new Set(ancestors.map((a) => a.path));
   for (const relation of node.meta.relations ?? []) {
     const target = graph.nodes.get(relation.target);
     if (!target) {
       throw new Error(`Broken relation: ${nodePath} -> ${relation.target} (target not found)`);
     }
+    if (ancestorPaths.has(relation.target)) continue;
     if (STRUCTURAL_RELATION_TYPES.has(relation.type)) {
       layers.push(buildStructuralRelationLayer(target, relation, graph.config));
     } else if (EVENT_RELATION_TYPES.has(relation.type)) {
       layers.push(buildEventRelationLayer(target, relation));
     }
   }
-  for (const tag of nodeTags) {
-    for (const aspect of graph.aspects) {
-      if (aspect.tag === tag) {
-        layers.push(buildAspectLayer(aspect));
-      }
-    }
-  }
   for (const flow of collectParticipatingFlows(graph, node)) {
-    layers.push(buildFlowLayer(flow));
-    for (const kPath of flow.knowledge ?? []) {
-      const norm = kPath.replace(/\/$/, "");
-      const k = graph.knowledge.find((item) => item.path === norm || item.path === kPath);
-      if (k && !seenKnowledge.has(k.path)) {
-        seenKnowledge.add(k.path);
-        layers.push(buildKnowledgeLayer(k, true));
+    layers.push(buildFlowLayer(flow, graph));
+  }
+  const allAspectIds = /* @__PURE__ */ new Set();
+  for (const l of layers) {
+    const aspects = l.attrs?.aspects;
+    if (aspects) {
+      for (const id of aspects.split(",").map((t) => t.trim()).filter(Boolean)) {
+        allAspectIds.add(id);
       }
     }
   }
+  const aspectsToInclude = resolveAspects(allAspectIds, graph.aspects);
+  for (const aspect of aspectsToInclude) {
+    layers.push(buildAspectLayer(aspect));
+  }
   const fullText = layers.map((l) => l.content).join("\n\n");
   const tokenCount = estimateTokens(fullText);
   const mapping = normalizeMappingPaths(node.meta.mapping);
@@ -1289,47 +1303,46 @@ async function buildContext(graph, nodePath) {
     tokenCount
   };
 }
-function collectKnowledgeItems(graph, nodePath, nodeTags, seenKnowledge) {
-  const result = [];
-  for (const k of graph.knowledge) {
-    if (k.scope === "global" && !seenKnowledge.has(k.path)) {
-      seenKnowledge.add(k.path);
-      result.push(k);
-    }
+function collectParticipatingFlows(graph, node) {
+  const paths = /* @__PURE__ */ new Set([node.path, ...collectAncestors(node).map((a) => a.path)]);
+  return graph.flows.filter((f) => f.nodes.some((n) => paths.has(n)));
+}
+function expandAspects(aspectIds, aspects) {
+  const idToAspect = /* @__PURE__ */ new Map();
+  for (const a of aspects) {
+    idToAspect.set(a.id, a);
   }
-  for (const k of graph.knowledge) {
-    if (typeof k.scope === "object" && "tags" in k.scope) {
-      const overlap = k.scope.tags.some((t) => nodeTags.has(t));
-      if (overlap && !seenKnowledge.has(k.path)) {
-        seenKnowledge.add(k.path);
-        result.push(k);
-      }
+  const result = [];
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  function collect(id) {
+    if (stack.has(id)) {
+      throw new Error(`Aspect implies cycle detected involving aspect '${id}'`);
     }
-  }
-  for (const k of graph.knowledge) {
-    if (typeof k.scope === "object" && "nodes" in k.scope) {
-      if (k.scope.nodes.includes(nodePath) && !seenKnowledge.has(k.path)) {
-        seenKnowledge.add(k.path);
-        result.push(k);
+    if (visited.has(id)) return;
+    stack.add(id);
+    visited.add(id);
+    result.push(id);
+    const aspect = idToAspect.get(id);
+    if (aspect) {
+      for (const implied of aspect.implies ?? []) {
+        collect(implied);
       }
     }
+    stack.delete(id);
   }
-  const node = graph.nodes.get(nodePath);
-  if (node?.meta.knowledge) {
-    for (const kPath of node.meta.knowledge) {
-      const norm = kPath.replace(/\/$/, "");
-      const k = graph.knowledge.find((item) => item.path === norm || item.path === kPath);
-      if (k && !seenKnowledge.has(k.path)) {
-        seenKnowledge.add(k.path);
-        result.push(k);
-      }
-    }
+  for (const id of aspectIds) {
+    collect(id);
   }
   return result;
 }
-function collectParticipatingFlows(graph, node) {
-  const paths = /* @__PURE__ */ new Set([node.path, ...collectAncestors(node).map((a) => a.path)]);
-  return graph.flows.filter((f) => f.nodes.some((n) => paths.has(n)));
+function resolveAspects(aspectIds, aspects) {
+  const idToAspect = /* @__PURE__ */ new Map();
+  for (const a of aspects) {
+    idToAspect.set(a.id, a);
+  }
+  const expandedIds = expandAspects([...aspectIds], aspects);
+  return expandedIds.map((id) => idToAspect.get(id)).filter((a) => a !== void 0);
 }
 function buildGlobalLayer(config) {
   let content = `**Project:** ${config.name}
@@ -1347,41 +1360,39 @@ ${config.standards || "(none)"}
 `;
   return { type: "global", label: "Global Context", content };
 }
-function buildKnowledgeLayer(k, fromFlow) {
-  const categoryLabel = k.category.charAt(0).toUpperCase() + k.category.slice(1);
-  const content = k.artifacts.map((a) => `### ${a.filename}
-${a.content}`).join("\n\n");
-  const label = fromFlow ? `Long-term Memory (from flow): ${k.name}` : `${categoryLabel}: ${k.name}`;
-  return {
-    type: "knowledge",
-    label,
-    content
-  };
-}
 function filterArtifactsByConfig(artifacts, config) {
   const allowed = new Set(Object.keys(config.artifacts ?? {}));
   return artifacts.filter((a) => allowed.has(a.filename));
 }
-function buildHierarchyLayer(ancestor, config) {
+function buildHierarchyLayer(ancestor, config, graph) {
   const filtered = filterArtifactsByConfig(ancestor.artifacts, config);
   const content = filtered.map((a) => `### ${a.filename}
 ${a.content}`).join("\n\n");
+  const nodeAspects = ancestor.meta.aspects ?? [];
+  const expanded = expandAspects(nodeAspects, graph.aspects);
+  const attrs = expanded.length > 0 ? { aspects: expanded.join(",") } : void 0;
   return {
     type: "hierarchy",
     label: `Module Context (${ancestor.path}/)`,
-    content
+    content,
+    attrs
   };
 }
-async function buildOwnLayer(node, config, graphRootPath) {
+async function buildOwnLayer(node, config, graphRootPath, graph) {
   const parts = [];
-  const nodeYamlPath = path7.join(graphRootPath, "model", node.path, "node.yaml");
-  try {
-    const nodeYamlContent = await readFile10(nodeYamlPath, "utf-8");
+  if (node.nodeYamlRaw) {
     parts.push(`### node.yaml
+${node.nodeYamlRaw.trim()}`);
+  } else {
+    const nodeYamlPath = path8.join(graphRootPath, "model", node.path, "node.yaml");
+    try {
+      const nodeYamlContent = await readFile10(nodeYamlPath, "utf-8");
+      parts.push(`### node.yaml
 ${nodeYamlContent.trim()}`);
-  } catch {
-    parts.push(`### node.yaml
+    } catch {
+      parts.push(`### node.yaml
 (not found)`);
+    }
   }
   const filtered = filterArtifactsByConfig(node.artifacts, config);
   for (const a of filtered) {
@@ -1389,10 +1400,14 @@ ${nodeYamlContent.trim()}`);
 ${a.content}`);
   }
   const content = parts.join("\n\n");
+  const nodeAspects = node.meta.aspects ?? [];
+  const expanded = expandAspects(nodeAspects, graph.aspects);
+  const attrs = expanded.length > 0 ? { aspects: expanded.join(",") } : void 0;
   return {
     type: "own",
     label: `Node: ${node.meta.name}`,
-    content
+    content,
+    attrs
   };
 }
 function buildStructuralRelationLayer(target, relation, config) {
@@ -1420,10 +1435,17 @@ ${a.content}`).join("\n\n");
     content += filtered.map((a) => `### ${a.filename}
 ${a.content}`).join("\n\n");
   }
+  const attrs = {
+    target: target.path,
+    type: relation.type
+  };
+  if (relation.consumes?.length) attrs.consumes = relation.consumes.join(", ");
+  if (relation.failure) attrs.failure = relation.failure;
   return {
     type: "relational",
     label: `Dependency: ${target.meta.name} (${relation.type}) \u2014 ${target.path}`,
-    content: content.trim()
+    content: content.trim(),
+    attrs
   };
 }
 function buildEventRelationLayer(target, relation) {
@@ -1436,10 +1458,17 @@ You listen for ${eventName}.`;
     content += `
 Consumes: ${relation.consumes.join(", ")}`;
   }
+  const attrs = {
+    target: target.path,
+    type: relation.type,
+    "event-name": eventName
+  };
+  if (relation.consumes?.length) attrs.consumes = relation.consumes.join(", ");
   return {
     type: "relational",
     label: `Event: ${eventName} [${relation.type}]`,
-    content
+    content,
+    attrs
   };
 }
 function buildAspectLayer(aspect) {
@@ -1447,17 +1476,21 @@ function buildAspectLayer(aspect) {
 ${a.content}`).join("\n\n");
   return {
     type: "aspects",
-    label: `${aspect.name} (tag: ${aspect.tag})`,
+    label: `${aspect.name} (aspect: ${aspect.id})`,
     content
   };
 }
-function buildFlowLayer(flow) {
+function buildFlowLayer(flow, graph) {
   const content = flow.artifacts.map((a) => `### ${a.filename}
 ${a.content}`).join("\n\n");
+  const flowAspects = flow.aspects ?? [];
+  const expanded = expandAspects(flowAspects, graph.aspects);
+  const attrs = expanded.length > 0 ? { aspects: expanded.join(",") } : void 0;
   return {
     type: "flows",
     label: `Flow: ${flow.name}`,
-    content: content || "(no artifacts)"
+    content: content || "(no artifacts)",
+    attrs
   };
 }
 function buildSections(layers, mapping) {
@@ -1471,12 +1504,16 @@ function buildSections(layers, mapping) {
   }
   return [
     { key: "Global", layers: layers.filter((l) => l.type === "global") },
-    { key: "Knowledge", layers: layers.filter((l) => l.type === "knowledge") },
     { key: "Hierarchy", layers: layers.filter((l) => l.type === "hierarchy") },
     { key: "OwnArtifacts", layers: ownLayers },
-    { key: "Dependencies", layers: layers.filter((l) => l.type === "relational") },
     { key: "Aspects", layers: layers.filter((l) => l.type === "aspects") },
-    { key: "Flows", layers: layers.filter((l) => l.type === "flows") }
+    {
+      key: "Relational",
+      layers: [
+        ...layers.filter((l) => l.type === "relational"),
+        ...layers.filter((l) => l.type === "flows")
+      ]
+    }
   ];
 }
 function collectAncestors(node) {
@@ -1488,30 +1525,27 @@ function collectAncestors(node) {
   }
   return ancestors;
 }
-
-// src/core/validator.ts
-import { readdir as readdir4 } from "fs/promises";
-import path9 from "path";
-
-// src/utils/git.ts
-import { execSync } from "child_process";
-import path8 from "path";
-function getLastCommitTimestamp(projectRoot, relativePath) {
-  const normalized = path8.normalize(relativePath).replace(/\\/g, "/");
-  try {
-    const out = execSync(`git log -1 --format=%ct -- "${normalized}"`, {
-      cwd: projectRoot,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-    const ts = parseInt(out.trim(), 10);
-    return Number.isNaN(ts) ? null : ts;
-  } catch {
-    return null;
+function collectEffectiveAspectIds(graph, nodePath) {
+  const node = graph.nodes.get(nodePath);
+  if (!node) return /* @__PURE__ */ new Set();
+  const raw = new Set(node.meta.aspects ?? []);
+  let ancestor = node.parent;
+  while (ancestor) {
+    for (const id of ancestor.meta.aspects ?? []) raw.add(id);
+    ancestor = ancestor.parent;
+  }
+  const ancestorPaths = /* @__PURE__ */ new Set([nodePath, ...collectAncestors(node).map((a) => a.path)]);
+  for (const flow of graph.flows) {
+    if (flow.nodes.some((n) => ancestorPaths.has(n))) {
+      for (const id of flow.aspects ?? []) raw.add(id);
+    }
   }
+  return new Set(expandAspects([...raw], graph.aspects));
 }
 
 // src/core/validator.ts
+import { readdir as readdir4 } from "fs/promises";
+import path9 from "path";
 var RESERVED_DIRS = /* @__PURE__ */ new Set();
 async function validate(graph, scope = "all") {
   const issues = [];
@@ -1534,46 +1568,60 @@ async function validate(graph, scope = "all") {
   }
   if (!graph.configError) {
     issues.push(...checkNodeTypes(graph));
-    issues.push(...checkTagsDefined(graph));
-    issues.push(...checkAspectTags(graph));
-    issues.push(...checkAspectTagUniqueness(graph));
+    issues.push(...checkAspectsDefined(graph));
+    issues.push(...checkAspectIds(graph));
+    issues.push(...checkAspectIdUniqueness(graph));
+    issues.push(...checkImpliedAspectsExist(graph));
+    issues.push(...checkImpliesNoCycles(graph));
+    issues.push(...checkRequiredAspectsCoverage(graph));
     issues.push(...checkRequiredArtifacts(graph));
-    issues.push(...await checkUnknownKnowledgeCategories(graph));
     issues.push(...checkInvalidArtifactConditions(graph));
-    issues.push(...checkScopeTagsDefined(graph));
-    issues.push(...await checkMissingPatternExamples(graph));
     issues.push(...await checkContextBudget(graph));
     issues.push(...checkHighFanOut(graph));
-    issues.push(...await checkStaleKnowledge(graph));
   }
   issues.push(...checkSchemas(graph));
   issues.push(...checkRelationTargets(graph));
   issues.push(...checkNoCycles(graph));
   issues.push(...checkMappingOverlap(graph));
-  issues.push(...checkBrokenKnowledgeRefs(graph));
+  issues.push(...await checkMappingPathsExist(graph));
   issues.push(...checkBrokenFlowRefs(graph));
-  issues.push(...checkBrokenScopeRefs(graph));
+  issues.push(...checkFlowAspectIds(graph));
   issues.push(...await checkDirectoriesHaveNodeYaml(graph));
   issues.push(...await checkShallowArtifacts(graph));
-  issues.push(...await checkUnreachableKnowledge(graph));
   issues.push(...checkUnpairedEvents(graph));
   let filtered = issues;
   let nodesScanned = graph.nodes.size;
   if (scope !== "all" && scope.trim()) {
     if (!graph.nodes.has(scope)) {
+      const parseError = (graph.nodeParseErrors ?? []).find(
+        (e) => e.nodePath === scope || scope.startsWith(e.nodePath + "/")
+      );
+      if (parseError) {
+        return {
+          issues: [{
+            severity: "error",
+            code: "E001",
+            rule: "invalid-node-yaml",
+            message: parseError.message,
+            nodePath: parseError.nodePath
+          }],
+          nodesScanned: 0
+        };
+      }
       return {
         issues: [{ severity: "error", rule: "invalid-scope", message: `Node not found: ${scope}` }],
         nodesScanned: 0
       };
     }
-    filtered = issues.filter((i) => !i.nodePath || i.nodePath === scope);
-    nodesScanned = 1;
+    const scopePrefix = scope + "/";
+    filtered = issues.filter((i) => !i.nodePath || i.nodePath === scope || i.nodePath.startsWith(scopePrefix));
+    nodesScanned = [...graph.nodes.keys()].filter((p) => p === scope || p.startsWith(scopePrefix)).length;
   }
   return { issues: filtered, nodesScanned };
 }
 function checkNodeTypes(graph) {
   const issues = [];
-  const allowedTypes = new Set(graph.config.node_types ?? []);
+  const allowedTypes = new Set((graph.config.node_types ?? []).map((t) => t.name));
   for (const [nodePath, node] of graph.nodes) {
     if (!allowedTypes.has(node.meta.type)) {
       issues.push({
@@ -1636,17 +1684,17 @@ function checkRelationTargets(graph) {
   }
   return issues;
 }
-function checkTagsDefined(graph) {
+function checkAspectsDefined(graph) {
   const issues = [];
-  const definedTags = new Set(graph.config.tags ?? []);
+  const validAspectIds = new Set(graph.aspects.map((a) => a.id));
   for (const [nodePath, node] of graph.nodes) {
-    for (const tag of node.meta.tags ?? []) {
-      if (!definedTags.has(tag)) {
+    for (const aspectId of node.meta.aspects ?? []) {
+      if (!validAspectIds.has(aspectId)) {
         issues.push({
           severity: "error",
           code: "E003",
-          rule: "unknown-tag",
-          message: `Tag '${tag}' not defined in config.yaml`,
+          rule: "unknown-aspect",
+          message: `Aspect '${aspectId}' has no corresponding directory in aspects/`,
           nodePath
         });
       }
@@ -1654,40 +1702,124 @@ function checkTagsDefined(graph) {
   }
   return issues;
 }
-function checkAspectTags(graph) {
-  const issues = [];
-  const definedTags = new Set(graph.config.tags ?? []);
-  for (const aspect of graph.aspects) {
-    if (!definedTags.has(aspect.tag)) {
-      issues.push({
-        severity: "error",
-        code: "E007",
-        rule: "broken-aspect-tag",
-        message: `Aspect '${aspect.name}' references undefined tag '${aspect.tag}'`
-      });
-    }
-  }
-  return issues;
+function checkAspectIds(_graph) {
+  return [];
 }
-function checkAspectTagUniqueness(graph) {
+function checkAspectIdUniqueness(graph) {
   const issues = [];
-  const byTag = /* @__PURE__ */ new Map();
+  const byId = /* @__PURE__ */ new Map();
   for (const aspect of graph.aspects) {
-    const names = byTag.get(aspect.tag) ?? [];
+    const names = byId.get(aspect.id) ?? [];
     names.push(aspect.name);
-    byTag.set(aspect.tag, names);
+    byId.set(aspect.id, names);
   }
-  for (const [tag, names] of byTag) {
+  for (const [id, names] of byId) {
     if (names.length <= 1) continue;
     issues.push({
       severity: "error",
       code: "E014",
       rule: "duplicate-aspect-binding",
-      message: `Tag '${tag}' is bound to multiple aspects (${names.join(", ")})`
+      message: `Aspect '${id}' is bound to multiple aspects (${names.join(", ")})`
     });
   }
   return issues;
 }
+function checkImpliedAspectsExist(graph) {
+  const issues = [];
+  const idToAspect = /* @__PURE__ */ new Map();
+  for (const a of graph.aspects) {
+    idToAspect.set(a.id, { name: a.name });
+  }
+  for (const aspect of graph.aspects) {
+    for (const impliedId of aspect.implies ?? []) {
+      if (!idToAspect.has(impliedId)) {
+        issues.push({
+          severity: "error",
+          code: "E016",
+          rule: "implied-aspect-missing",
+          message: `Aspect '${aspect.name}' implies '${impliedId}' but no aspect with that id exists in aspects/`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function checkImpliesNoCycles(graph) {
+  const idToAspect = /* @__PURE__ */ new Map();
+  for (const a of graph.aspects) {
+    idToAspect.set(a.id, { implies: a.implies });
+  }
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = /* @__PURE__ */ new Map();
+  for (const id of idToAspect.keys()) color.set(id, WHITE);
+  const issues = [];
+  function dfs(id, pathArr) {
+    color.set(id, GRAY);
+    pathArr.push(id);
+    const aspect = idToAspect.get(id);
+    for (const implied of aspect?.implies ?? []) {
+      if (color.get(implied) === GRAY) {
+        const cycle = pathArr.slice(pathArr.indexOf(implied)).concat(implied);
+        issues.push({
+          severity: "error",
+          code: "E017",
+          rule: "aspect-implies-cycle",
+          message: `Aspect implies cycle: ${cycle.join(" \u2192 ")}`
+        });
+        pathArr.pop();
+        color.set(id, BLACK);
+        return true;
+      }
+      if (color.get(implied) === WHITE && dfs(implied, pathArr)) {
+        pathArr.pop();
+        color.set(id, BLACK);
+        return true;
+      }
+    }
+    pathArr.pop();
+    color.set(id, BLACK);
+    return false;
+  }
+  for (const id of idToAspect.keys()) {
+    if (color.get(id) === WHITE) {
+      dfs(id, []);
+    }
+  }
+  return issues;
+}
+function checkRequiredAspectsCoverage(graph) {
+  const issues = [];
+  const typeConfig = new Map(
+    (graph.config.node_types ?? []).map((t) => [t.name, t.required_aspects ?? []])
+  );
+  for (const [nodePath, node] of graph.nodes) {
+    if (node.meta.blackbox) continue;
+    const requiredAspects = typeConfig.get(node.meta.type);
+    if (!requiredAspects || requiredAspects.length === 0) continue;
+    const nodeAspects = node.meta.aspects ?? [];
+    let effectiveAspects;
+    try {
+      effectiveAspects = resolveAspects(nodeAspects, graph.aspects);
+    } catch {
+      continue;
+    }
+    const effectiveAspectIds = new Set(effectiveAspects.map((a) => a.id));
+    for (const required of requiredAspects) {
+      if (!effectiveAspectIds.has(required)) {
+        issues.push({
+          severity: "warning",
+          code: "W011",
+          rule: "missing-required-aspect-coverage",
+          message: `Node '${nodePath}' (type: ${node.meta.type}) missing required aspect coverage for '${required}'`,
+          nodePath
+        });
+      }
+    }
+  }
+  return issues;
+}
 function checkNoCycles(graph) {
   const WHITE = 0;
   const GRAY = 1;
@@ -1740,6 +1872,9 @@ function arePathsOverlapping(pathA, pathB) {
   if (pathA === pathB) return true;
   return pathA.startsWith(pathB + "/") || pathB.startsWith(pathA + "/");
 }
+function isAncestorNode(possibleAncestor, possibleDescendant) {
+  return possibleDescendant.startsWith(possibleAncestor + "/");
+}
 function checkMappingOverlap(graph) {
   const issues = [];
   const ownership = [];
@@ -1755,6 +1890,9 @@ function checkMappingOverlap(graph) {
       const candidate = ownership[nestedIndex];
       if (current.nodePath === candidate.nodePath) continue;
       if (!arePathsOverlapping(current.mappingPath, candidate.mappingPath)) continue;
+      const isContainment = current.mappingPath !== candidate.mappingPath;
+      const isHierarchical = isAncestorNode(current.nodePath, candidate.nodePath) || isAncestorNode(candidate.nodePath, current.nodePath);
+      if (isContainment && isHierarchical) continue;
       issues.push({
         severity: "error",
         code: "E009",
@@ -1766,6 +1904,29 @@ function checkMappingOverlap(graph) {
   }
   return issues;
 }
+async function checkMappingPathsExist(graph) {
+  const issues = [];
+  const projectRoot = path9.dirname(graph.rootPath);
+  const { access: access4 } = await import("fs/promises");
+  for (const [nodePath, node] of graph.nodes) {
+    const mappingPaths = normalizeMappingPaths(node.meta.mapping);
+    for (const mp of mappingPaths) {
+      const absPath = path9.join(projectRoot, mp);
+      try {
+        await access4(absPath);
+      } catch {
+        issues.push({
+          severity: "warning",
+          code: "W012",
+          rule: "mapping-path-missing",
+          message: `Mapping path '${mp}' does not exist on disk`,
+          nodePath
+        });
+      }
+    }
+  }
+  return issues;
+}
 function getIncomingRelationSources(graph, nodePath) {
   const sources = [];
   for (const [srcPath, node] of graph.nodes) {
@@ -1789,9 +1950,10 @@ function artifactRequiredReason(graph, nodePath, node, required) {
     const count = node.meta.relations?.length ?? 0;
     return count > 0 ? `${count} outgoing relation(s)` : null;
   }
-  if (when.startsWith("has_tag:")) {
-    const tag = when.slice(8);
-    return (node.meta.tags ?? []).includes(tag) ? `node has tag '${tag}'` : null;
+  if (when.startsWith("has_aspect:") || when.startsWith("has_tag:")) {
+    const prefix = when.startsWith("has_aspect:") ? "has_aspect:" : "has_tag:";
+    const aspectId = when.slice(prefix.length);
+    return (node.meta.aspects ?? []).includes(aspectId) ? `node has aspect '${aspectId}'` : null;
   }
   return null;
 }
@@ -1831,29 +1993,9 @@ function checkRequiredArtifacts(graph) {
   }
   return issues;
 }
-function checkBrokenKnowledgeRefs(graph) {
-  const issues = [];
-  const knowledgePaths = new Set(graph.knowledge.map((k) => k.path));
-  for (const [nodePath, node] of graph.nodes) {
-    for (const kPath of node.meta.knowledge ?? []) {
-      const norm = kPath.replace(/\/$/, "");
-      if (!knowledgePaths.has(norm) && !knowledgePaths.has(kPath)) {
-        issues.push({
-          severity: "error",
-          code: "E005",
-          rule: "broken-knowledge-ref",
-          message: `Knowledge ref '${kPath}' does not resolve to existing knowledge item`,
-          nodePath
-        });
-      }
-    }
-  }
-  return issues;
-}
 function checkBrokenFlowRefs(graph) {
   const issues = [];
   const nodePaths = new Set(graph.nodes.keys());
-  const knowledgePaths = new Set(graph.knowledge.map((k) => k.path));
   for (const flow of graph.flows) {
     for (const n of flow.nodes) {
       if (!nodePaths.has(n)) {
@@ -1865,107 +2007,43 @@ function checkBrokenFlowRefs(graph) {
         });
       }
     }
-    for (const kPath of flow.knowledge ?? []) {
-      const norm = kPath.replace(/\/$/, "");
-      if (!knowledgePaths.has(norm) && !knowledgePaths.has(kPath)) {
+  }
+  return issues;
+}
+function checkFlowAspectIds(graph) {
+  const issues = [];
+  const validAspectIds = new Set(graph.aspects.map((a) => a.id));
+  for (const flow of graph.flows) {
+    for (const aspectId of flow.aspects ?? []) {
+      if (!validAspectIds.has(aspectId)) {
         issues.push({
           severity: "error",
-          code: "E005",
-          rule: "broken-knowledge-ref",
-          message: `Flow '${flow.name}' references non-existent knowledge '${kPath}'`,
-          nodePath: `flows/${flow.name}`
+          code: "E007",
+          rule: "broken-aspect-ref",
+          message: `Flow '${flow.name}' references aspect '${aspectId}' but no aspect with that id exists in aspects/`
         });
       }
     }
   }
   return issues;
 }
-function checkBrokenScopeRefs(graph) {
+function checkInvalidArtifactConditions(graph) {
   const issues = [];
-  const nodePaths = new Set(graph.nodes.keys());
-  for (const k of graph.knowledge) {
-    if (typeof k.scope === "object" && "nodes" in k.scope) {
-      for (const n of k.scope.nodes) {
-        if (!nodePaths.has(n)) {
-          issues.push({
-            severity: "error",
-            code: "E008",
-            rule: "broken-scope-ref",
-            message: `Knowledge '${k.path}' scope references non-existent node '${n}'`
-          });
-        }
-      }
-    }
-  }
-  return issues;
-}
-function checkScopeTagsDefined(graph) {
-  const issues = [];
-  const definedTags = new Set(graph.config.tags ?? []);
-  for (const k of graph.knowledge) {
-    if (typeof k.scope !== "object" || !("tags" in k.scope)) continue;
-    for (const tag of k.scope.tags) {
-      if (definedTags.has(tag)) continue;
-      issues.push({
-        severity: "error",
-        code: "E008",
-        rule: "broken-scope-ref",
-        message: `Knowledge '${k.path}' scope references undefined tag '${tag}'`
-      });
-    }
-  }
-  return issues;
-}
-async function checkUnknownKnowledgeCategories(graph) {
-  const issues = [];
-  const categorySet = new Set((graph.config.knowledge_categories ?? []).map((c) => c.name));
-  const knowledgeDir = path9.join(graph.rootPath, "knowledge");
-  const existingDirs = /* @__PURE__ */ new Set();
-  try {
-    const entries = await readdir4(knowledgeDir, { withFileTypes: true });
-    for (const e of entries) {
-      if (!e.isDirectory()) continue;
-      if (e.name.startsWith(".")) continue;
-      existingDirs.add(e.name);
-      if (!categorySet.has(e.name)) {
-        issues.push({
-          severity: "error",
-          code: "E011",
-          rule: "unknown-knowledge-category",
-          message: `Directory knowledge/${e.name}/ does not match any config.knowledge_categories`
-        });
-      }
-    }
-  } catch {
-  }
-  for (const cat of graph.config.knowledge_categories ?? []) {
-    if (!existingDirs.has(cat.name)) {
-      issues.push({
-        severity: "error",
-        code: "E017",
-        rule: "missing-knowledge-category-dir",
-        message: `Category '${cat.name}' in config has no knowledge/${cat.name}/ directory`
-      });
-    }
-  }
-  return issues;
-}
-function checkInvalidArtifactConditions(graph) {
-  const issues = [];
-  const definedTags = new Set(graph.config.tags ?? []);
-  const artifacts = graph.config.artifacts ?? {};
-  for (const [artifactName, config] of Object.entries(artifacts)) {
-    const required = config.required;
-    if (typeof required === "object" && required && "when" in required) {
-      const when = required.when;
-      if (when.startsWith("has_tag:")) {
-        const tag = when.slice(8);
-        if (!definedTags.has(tag)) {
+  const validAspectIds = new Set(graph.aspects.map((a) => a.id));
+  const artifacts = graph.config.artifacts ?? {};
+  for (const [artifactName, config] of Object.entries(artifacts)) {
+    const required = config.required;
+    if (typeof required === "object" && required && "when" in required) {
+      const when = required.when;
+      if (when.startsWith("has_aspect:") || when.startsWith("has_tag:")) {
+        const prefix = when.startsWith("has_aspect:") ? "has_aspect:" : "has_tag:";
+        const aspectId = when.slice(prefix.length);
+        if (!validAspectIds.has(aspectId)) {
           issues.push({
             severity: "error",
             code: "E013",
             rule: "invalid-artifact-condition",
-            message: `Artifact '${artifactName}' condition has_tag:${tag} references undefined tag`
+            message: `Artifact '${artifactName}' condition has_aspect:${aspectId} has no corresponding aspect in aspects/`
           });
         }
       }
@@ -1983,7 +2061,7 @@ async function checkShallowArtifacts(graph) {
           severity: "warning",
           code: "W002",
           rule: "shallow-artifact",
-          message: `Artifact '${art.filename}' is below minimum length (${art.content.length} < ${minLen})`,
+          message: `Artifact '${art.filename}' is below minimum length (${art.content.trim().length} < ${minLen})`,
           nodePath
         });
       }
@@ -1991,99 +2069,6 @@ async function checkShallowArtifacts(graph) {
   }
   return issues;
 }
-async function checkUnreachableKnowledge(graph) {
-  const issues = [];
-  const nodePaths = new Set(graph.nodes.keys());
-  const nodeTags = /* @__PURE__ */ new Map();
-  for (const [p, n] of graph.nodes) {
-    nodeTags.set(p, new Set(n.meta.tags ?? []));
-  }
-  const knowledgeReachable = /* @__PURE__ */ new Set();
-  for (const k of graph.knowledge) {
-    if (k.scope === "global") {
-      knowledgeReachable.add(k.path);
-      continue;
-    }
-    if (typeof k.scope === "object" && "tags" in k.scope) {
-      for (const [, tags] of nodeTags) {
-        if (k.scope.tags.some((t) => tags.has(t))) {
-          knowledgeReachable.add(k.path);
-          break;
-        }
-      }
-    }
-    if (typeof k.scope === "object" && "nodes" in k.scope) {
-      if (k.scope.nodes.some((n) => nodePaths.has(n))) {
-        knowledgeReachable.add(k.path);
-      }
-    }
-  }
-  for (const [, node] of graph.nodes) {
-    for (const kPath of node.meta.knowledge ?? []) {
-      const k = graph.knowledge.find(
-        (i) => i.path === kPath || i.path === kPath.replace(/\/$/, "")
-      );
-      if (k) knowledgeReachable.add(k.path);
-    }
-  }
-  for (const flow of graph.flows) {
-    for (const kPath of flow.knowledge ?? []) {
-      const k = graph.knowledge.find(
-        (i) => i.path === kPath || i.path === kPath.replace(/\/$/, "")
-      );
-      if (k) knowledgeReachable.add(k.path);
-    }
-  }
-  for (const k of graph.knowledge) {
-    if (!knowledgeReachable.has(k.path)) {
-      issues.push({
-        severity: "warning",
-        code: "W003",
-        rule: "unreachable-knowledge",
-        message: `Knowledge '${k.path}' does not reach any context package`
-      });
-    }
-  }
-  return issues;
-}
-async function checkMissingPatternExamples(graph) {
-  const issues = [];
-  const hasPatterns = (graph.config.knowledge_categories ?? []).some((c) => c.name === "patterns");
-  if (!hasPatterns) return issues;
-  const patternsDir = path9.join(graph.rootPath, "knowledge", "patterns");
-  try {
-    const entries = await readdir4(patternsDir, { withFileTypes: true });
-    const exampleExtensions = /* @__PURE__ */ new Set([
-      ".ts",
-      ".js",
-      ".tsx",
-      ".jsx",
-      ".py",
-      ".go",
-      ".rs",
-      ".java",
-      ".kt"
-    ]);
-    for (const e of entries) {
-      if (!e.isDirectory()) continue;
-      const itemDir = path9.join(patternsDir, e.name);
-      const itemEntries = await readdir4(itemDir, { withFileTypes: true });
-      const hasExample = itemEntries.some(
-        (f) => f.isFile() && f.name !== "knowledge.yaml" && (f.name.startsWith("example") || exampleExtensions.has(path9.extname(f.name).toLowerCase()))
-      );
-      if (!hasExample) {
-        issues.push({
-          severity: "warning",
-          code: "W004",
-          rule: "missing-example",
-          message: `Pattern 'patterns/${e.name}' has no example file`
-        });
-      }
-    }
-  } catch {
-  }
-  return issues;
-}
 function checkHighFanOut(graph) {
   const issues = [];
   const maxRel = graph.config.quality?.max_direct_relations ?? 10;
@@ -2101,57 +2086,6 @@ function checkHighFanOut(graph) {
   }
   return issues;
 }
-function getNodesInScope(k, graph) {
-  if (k.scope === "global") {
-    return [...graph.nodes.keys()];
-  }
-  if (typeof k.scope === "object" && "nodes" in k.scope && k.scope.nodes) {
-    return k.scope.nodes.filter((p) => graph.nodes.has(p));
-  }
-  if (typeof k.scope === "object" && "tags" in k.scope && k.scope.tags) {
-    const tagSet = new Set(k.scope.tags);
-    return [...graph.nodes.keys()].filter((p) => {
-      const node = graph.nodes.get(p);
-      return (node.meta.tags ?? []).some((t) => tagSet.has(t));
-    });
-  }
-  return [];
-}
-async function checkStaleKnowledge(graph) {
-  const issues = [];
-  const stalenessDays = graph.config.quality?.knowledge_staleness_days ?? 90;
-  const projectRoot = path9.dirname(graph.rootPath);
-  const yggRel = path9.relative(projectRoot, graph.rootPath).replace(/\\/g, "/") || ".yggdrasil";
-  for (const k of graph.knowledge) {
-    const scopeNodes = getNodesInScope(k, graph);
-    if (scopeNodes.length === 0) continue;
-    const kPath = `${yggRel}/knowledge/${k.path}`;
-    const tK = getLastCommitTimestamp(projectRoot, kPath);
-    if (tK === null) continue;
-    let maxTp = 0;
-    let latestNode = "";
-    for (const nodePath of scopeNodes) {
-      const nodePathRel = `${yggRel}/model/${nodePath}`;
-      const tP = getLastCommitTimestamp(projectRoot, nodePathRel);
-      if (tP !== null && tP > maxTp) {
-        maxTp = tP;
-        latestNode = nodePath;
-      }
-    }
-    if (maxTp === 0) continue;
-    const diffDays = (maxTp - tK) / (60 * 60 * 24);
-    if (diffDays > stalenessDays) {
-      issues.push({
-        severity: "warning",
-        code: "W008",
-        rule: "stale-knowledge",
-        message: `Knowledge '${k.path}' may be stale: node '${latestNode}' modified ${Math.floor(diffDays)} days later (Git commits)`,
-        nodePath: latestNode
-      });
-    }
-  }
-  return issues;
-}
 function checkUnpairedEvents(graph) {
   const issues = [];
   const emitsTo = /* @__PURE__ */ new Map();
@@ -2200,7 +2134,7 @@ function checkUnpairedEvents(graph) {
   }
   return issues;
 }
-var REQUIRED_SCHEMAS = ["node", "aspect", "flow", "knowledge"];
+var REQUIRED_SCHEMAS = ["node", "aspect", "flow"];
 function checkSchemas(graph) {
   const issues = [];
   const present = new Set(graph.schemas.map((s) => s.schemaType));
@@ -2210,7 +2144,7 @@ function checkSchemas(graph) {
         severity: "warning",
         code: "W010",
         rule: "missing-schema",
-        message: `Schema '${required}.yaml' missing from .yggdrasil/templates/`
+        message: `Schema '${required}.yaml' missing from .yggdrasil/schemas/`
       });
     }
   }
@@ -2224,16 +2158,27 @@ async function checkDirectoriesHaveNodeYaml(graph) {
     const hasNodeYaml = entries.some((e) => e.isFile() && e.name === "node.yaml");
     const dirName = path9.basename(dirPath);
     if (RESERVED_DIRS.has(dirName)) return;
-    const hasContent = entries.some((e) => e.isFile()) || entries.some((e) => e.isDirectory());
+    const hasFiles = entries.some((e) => e.isFile());
+    const hasSubdirs = entries.some((e) => e.isDirectory() && !RESERVED_DIRS.has(e.name) && !e.name.startsWith("."));
     const graphPath = segments.join("/");
-    if (hasContent && !hasNodeYaml && graphPath !== "") {
-      issues.push({
-        severity: "error",
-        code: "E015",
-        rule: "missing-node-yaml",
-        message: `Directory '${graphPath}' has content but no node.yaml`,
-        nodePath: graphPath
-      });
+    if (!hasNodeYaml && graphPath !== "") {
+      if (hasFiles) {
+        issues.push({
+          severity: "error",
+          code: "E015",
+          rule: "missing-node-yaml",
+          message: `Directory '${graphPath}' has files but no node.yaml`,
+          nodePath: graphPath
+        });
+      } else if (hasSubdirs) {
+        issues.push({
+          severity: "warning",
+          code: "W013",
+          rule: "directory-without-node",
+          message: `Directory '${graphPath}' has subdirectories but no node.yaml \u2014 consider creating a node`,
+          nodePath: graphPath
+        });
+      }
     }
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
@@ -2255,26 +2200,26 @@ async function checkDirectoriesHaveNodeYaml(graph) {
 }
 async function checkContextBudget(graph) {
   const issues = [];
-  const warningThreshold = graph.config.quality?.context_budget.warning ?? 5e3;
-  const errorThreshold = graph.config.quality?.context_budget.error ?? 1e4;
+  const warningThreshold = graph.config.quality?.context_budget.warning ?? 1e4;
+  const errorThreshold = graph.config.quality?.context_budget.error ?? 2e4;
   for (const [nodePath, node] of graph.nodes) {
     if (node.meta.blackbox) continue;
     try {
-      const pkg = await buildContext(graph, nodePath);
-      if (pkg.tokenCount >= errorThreshold) {
+      const pkg2 = await buildContext(graph, nodePath);
+      if (pkg2.tokenCount >= errorThreshold) {
         issues.push({
           severity: "warning",
           code: "W006",
           rule: "budget-error",
-          message: `Context is ${pkg.tokenCount.toLocaleString()} tokens (error threshold: ${errorThreshold.toLocaleString()}) \u2014 blocks materialization, node must be split`,
+          message: `Context is ${pkg2.tokenCount.toLocaleString()} tokens (error threshold: ${errorThreshold.toLocaleString()}) \u2014 blocks materialization, node must be split`,
           nodePath
         });
-      } else if (pkg.tokenCount >= warningThreshold) {
+      } else if (pkg2.tokenCount >= warningThreshold) {
         issues.push({
           severity: "warning",
           code: "W005",
           rule: "budget-warning",
-          message: `Context is ${pkg.tokenCount.toLocaleString()} tokens (warning threshold: ${warningThreshold.toLocaleString()}). Consider splitting the node or reducing dependencies.`,
+          message: `Context is ${pkg2.tokenCount.toLocaleString()} tokens (warning threshold: ${warningThreshold.toLocaleString()}). Consider splitting the node or reducing dependencies.`,
           nodePath
         });
       }
@@ -2284,75 +2229,133 @@ async function checkContextBudget(graph) {
   return issues;
 }
 
-// src/formatters/markdown.ts
-function formatContextMarkdown(pkg) {
-  let md = "";
-  md += `# Context Package: ${pkg.nodeName}
-`;
-  md += `# Path: ${pkg.nodePath}
-`;
-  md += `# Generated: ${(/* @__PURE__ */ new Date()).toISOString()}
-
-`;
-  md += `---
-
-`;
-  for (const section of pkg.sections) {
-    if (section.layers.length === 0) continue;
-    md += `## ${section.key}
+// src/formatters/context-text.ts
+function escapeAttr(val) {
+  return val.replace(/"/g, "&quot;");
+}
+function formatLayer(layer) {
+  switch (layer.type) {
+    case "global":
+      return `<global>
+${layer.content}
+</global>`;
+    case "hierarchy": {
+      const pathMatch = layer.label.match(/\((.+)\/\)/);
+      const pathAttr = pathMatch ? ` path="${escapeAttr(pathMatch[1])}"` : "";
+      const aspectsAttr = layer.attrs?.aspects ? ` aspects="${escapeAttr(layer.attrs.aspects)}"` : "";
+      return `<hierarchy${pathAttr}${aspectsAttr}>
+${layer.content}
+</hierarchy>`;
+    }
+    case "own": {
+      if (layer.label === "Materialization Target") {
+        return `<materialization-target paths="${escapeAttr(layer.content)}" />`;
+      }
+      const ownAspectsAttr = layer.attrs?.aspects ? ` aspects="${escapeAttr(layer.attrs.aspects)}"` : "";
+      return `<own-artifacts${ownAspectsAttr}>
+${layer.content}
+</own-artifacts>`;
+    }
+    case "aspects": {
+      const nameMatch = layer.label.match(/^(.+?) \(aspect: (.+)\)$/);
+      const name = nameMatch ? escapeAttr(nameMatch[1]) : "";
+      const id = nameMatch ? escapeAttr(nameMatch[2]) : "";
+      return `<aspect name="${name}" id="${id}">
+${layer.content}
+</aspect>`;
+    }
+    case "relational": {
+      const attrs = layer.attrs ?? {};
+      const attrStr = Object.entries(attrs).map(([k, v]) => ` ${k}="${escapeAttr(v)}"`).join("");
+      const tagName = attrs.type && ["emits", "listens"].includes(attrs.type) ? "event" : "dependency";
+      return `<${tagName}${attrStr}>
+${layer.content}
+</${tagName}>`;
+    }
+    case "flows": {
+      const flowName = layer.label.replace(/^Flow: /, "").trim();
+      const flowAspectsAttr = layer.attrs?.aspects ? ` aspects="${escapeAttr(layer.attrs.aspects)}"` : "";
+      return `<flow name="${escapeAttr(flowName)}"${flowAspectsAttr}>
+${layer.content}
+</flow>`;
+    }
+    default:
+      return layer.content;
+  }
+}
+function formatContextText(pkg2) {
+  const attrs = [
+    `node-path="${escapeAttr(pkg2.nodePath)}"`,
+    `node-name="${escapeAttr(pkg2.nodeName)}"`,
+    `token-count="${pkg2.tokenCount}"`
+  ].join(" ");
+  let out = `<context-package ${attrs}>
 
 `;
+  for (const section of pkg2.sections) {
     for (const layer of section.layers) {
-      md += `### ${layer.label}
-
-`;
-      md += layer.content;
-      md += `
-
-`;
+      out += formatLayer(layer) + "\n\n";
     }
-    md += `---
-
-`;
   }
-  md += `Context size: ${pkg.tokenCount.toLocaleString()} tokens
-`;
-  md += `Layers: ${pkg.layers.map((l) => l.type).join(", ")}
-`;
-  return md;
+  out += "</context-package>";
+  return out;
 }
 
 // src/cli/build-context.ts
+function collectRelevantNodePaths(graph, nodePath) {
+  const relevant = /* @__PURE__ */ new Set();
+  const node = graph.nodes.get(nodePath);
+  if (!node) return relevant;
+  relevant.add(nodePath);
+  for (const ancestor of collectAncestors(node)) {
+    relevant.add(ancestor.path);
+  }
+  for (const rel of node.meta.relations ?? []) {
+    relevant.add(rel.target);
+  }
+  return relevant;
+}
 function registerBuildCommand(program2) {
   program2.command("build-context").description("Assemble a context package for one node").requiredOption("--node <node-path>", "Node path relative to .yggdrasil/model/").action(async (options) => {
     try {
       const graph = await loadGraph(process.cwd());
+      const nodePath = options.node.trim().replace(/^\.\//, "").replace(/\/$/, "");
+      const relevantNodes = collectRelevantNodePaths(graph, nodePath);
       const validationResult = await validate(graph, "all");
-      const structuralErrors = validationResult.issues.filter(
-        (issue) => issue.severity === "error"
+      const relevantErrors = validationResult.issues.filter(
+        (issue) => issue.severity === "error" && // Global errors (no nodePath) always block — e.g., E012 invalid config
+        (!issue.nodePath || relevantNodes.has(issue.nodePath))
       );
-      if (structuralErrors.length > 0) {
-        process.stderr.write(
-          `Error: build-context requires a structurally valid graph (${structuralErrors.length} errors found).
-`
-        );
+      if (relevantErrors.length > 0) {
+        const totalErrors = validationResult.issues.filter((i) => i.severity === "error").length;
+        const skippedErrors = totalErrors - relevantErrors.length;
+        let msg = `Error: build-context blocked by ${relevantErrors.length} error(s) affecting this node's context.
+`;
+        if (skippedErrors > 0) {
+          msg += `(${skippedErrors} unrelated error(s) in other nodes ignored.)
+`;
+        }
+        for (const err of relevantErrors) {
+          const loc = err.nodePath ? `${err.nodePath}: ` : "";
+          msg += `  ${err.code ?? ""} ${loc}${err.message}
+`;
+        }
+        process.stderr.write(msg);
         process.exit(1);
       }
-      const nodePath = options.node.trim().replace(/\/$/, "");
-      const pkg = await buildContext(graph, nodePath);
-      const warningThreshold = graph.config.quality?.context_budget.warning ?? 5e3;
-      const errorThreshold = graph.config.quality?.context_budget.error ?? 1e4;
-      const budgetStatus = pkg.tokenCount >= errorThreshold ? "error" : pkg.tokenCount >= warningThreshold ? "warning" : "ok";
-      let output = formatContextMarkdown(pkg);
+      const pkg2 = await buildContext(graph, nodePath);
+      const warningThreshold = graph.config.quality?.context_budget.warning ?? 1e4;
+      const errorThreshold = graph.config.quality?.context_budget.error ?? 2e4;
+      const budgetStatus = pkg2.tokenCount >= errorThreshold ? "error" : pkg2.tokenCount >= warningThreshold ? "warning" : "ok";
+      let output = formatContextText(pkg2);
       output += `Budget status: ${budgetStatus}
 `;
       process.stdout.write(output);
       if (budgetStatus === "error") {
         process.stderr.write(
-          `Error: context package exceeds error budget (${pkg.tokenCount} >= ${errorThreshold}).
+          `Warning: context package exceeds error budget (${pkg2.tokenCount} >= ${errorThreshold}). Consider splitting the node.
 `
         );
-        process.exit(1);
       }
     } catch (error) {
       process.stderr.write(`Error: ${error.message}
@@ -2368,7 +2371,8 @@ function registerValidateCommand(program2) {
   program2.command("validate").description("Validate graph structural integrity and completeness signals").option("--scope <scope>", "Scope: all or node-path (default: all)", "all").action(async (options) => {
     try {
       const graph = await loadGraph(process.cwd(), { tolerateInvalidConfig: true });
-      const scope = (options.scope ?? "all").trim() || "all";
+      const rawScope = (options.scope ?? "all").trim() || "all";
+      const scope = rawScope === "all" ? "all" : rawScope.replace(/^\.\//, "").replace(/\/+$/, "");
       const result = await validate(graph, scope);
       process.stdout.write(`${result.nodesScanned} nodes scanned
 
@@ -2411,40 +2415,33 @@ import chalk2 from "chalk";
 
 // src/io/drift-state-store.ts
 import { readFile as readFile11, writeFile as writeFile3 } from "fs/promises";
-import { parse as parseYaml7, stringify as stringifyYaml } from "yaml";
 import path10 from "path";
+import { parse as yamlParse } from "yaml";
 var DRIFT_STATE_FILE = ".drift-state";
-function getCanonicalHash(entry) {
-  return typeof entry === "string" ? entry : entry.hash;
-}
-function getFileHashes(entry) {
-  return typeof entry === "object" ? entry.files : void 0;
-}
 async function readDriftState(yggRoot) {
-  const filePath = path10.join(yggRoot, DRIFT_STATE_FILE);
   try {
-    const content = await readFile11(filePath, "utf-8");
-    const raw = parseYaml7(content);
-    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
-      const result = {};
-      for (const [k, v] of Object.entries(raw)) {
-        if (typeof k === "string" && typeof v === "string") {
-          result[k] = v;
-        } else if (typeof k === "string" && typeof v === "object" && v !== null && "hash" in v) {
-          result[k] = v;
-        }
+    const content = await readFile11(path10.join(yggRoot, DRIFT_STATE_FILE), "utf-8");
+    let raw;
+    try {
+      raw = JSON.parse(content);
+    } catch {
+      raw = yamlParse(content);
+    }
+    if (!raw || typeof raw !== "object") return {};
+    const state = {};
+    for (const [key, value] of Object.entries(raw)) {
+      if (typeof value === "object" && value !== null && "hash" in value) {
+        state[key] = value;
       }
-      return result;
     }
-    return {};
+    return state;
   } catch {
     return {};
   }
 }
 async function writeDriftState(yggRoot, state) {
-  const filePath = path10.join(yggRoot, DRIFT_STATE_FILE);
-  const content = stringifyYaml(state);
-  await writeFile3(filePath, content, "utf-8");
+  const content = JSON.stringify(state);
+  await writeFile3(path10.join(yggRoot, DRIFT_STATE_FILE), content, "utf-8");
 }
 
 // src/utils/hash.ts
@@ -2458,139 +2455,238 @@ async function hashFile(filePath) {
   const content = await readFile12(filePath);
   return createHash("sha256").update(content).digest("hex");
 }
-async function hashPath(targetPath, options = {}) {
-  const projectRoot = options.projectRoot ? path11.resolve(options.projectRoot) : void 0;
-  const gitignoreMatcher = await loadGitignoreMatcher(projectRoot);
-  const targetStat = await stat3(targetPath);
-  if (targetStat.isFile()) {
-    if (isIgnoredPath(targetPath, projectRoot, gitignoreMatcher)) {
-      return hashString("");
-    }
-    return hashFile(targetPath);
+async function loadRootGitignoreStack(projectRoot) {
+  if (!projectRoot) return [];
+  try {
+    const content = await readFile12(path11.join(projectRoot, ".gitignore"), "utf-8");
+    const matcher = ignoreFactory();
+    matcher.add(content);
+    return [{ basePath: projectRoot, matcher }];
+  } catch {
+    return [];
   }
-  if (targetStat.isDirectory()) {
-    const fileHashes = await collectDirectoryFileHashes(targetPath, targetPath, {
-      projectRoot,
-      gitignoreMatcher
-    });
-    const digestInput = fileHashes.sort((a, b) => a.path.localeCompare(b.path)).map((entry) => `${entry.path}:${entry.hash}`).join("\n");
-    return hashString(digestInput);
+}
+function isIgnoredByStack(candidatePath, stack) {
+  for (const { basePath, matcher } of stack) {
+    const relativePath = path11.relative(basePath, candidatePath);
+    if (relativePath === "" || relativePath.startsWith("..")) continue;
+    if (matcher.ignores(relativePath) || matcher.ignores(relativePath + "/")) return true;
   }
-  throw new Error(`Unsupported mapping path type: ${targetPath}`);
+  return false;
 }
-async function collectDirectoryFileHashes(directoryPath, rootDirectoryPath, options) {
-  const entries = await readdir5(directoryPath, { withFileTypes: true });
-  const result = [];
-  for (const entry of entries) {
-    const absoluteChildPath = path11.join(directoryPath, entry.name);
-    if (isIgnoredPath(absoluteChildPath, options.projectRoot, options.gitignoreMatcher)) {
-      continue;
-    }
-    if (entry.isDirectory()) {
-      const nested = await collectDirectoryFileHashes(
-        absoluteChildPath,
-        rootDirectoryPath,
-        options
-      );
-      for (const nestedEntry of nested) {
-        result.push({
-          path: path11.relative(rootDirectoryPath, path11.join(absoluteChildPath, nestedEntry.path)),
-          hash: nestedEntry.hash
+function hashString(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+async function hashTrackedFiles(projectRoot, trackedFiles, storedFileData, excludePrefixes) {
+  const fileHashes = {};
+  const fileMtimes = {};
+  const gitignoreStack = await loadRootGitignoreStack(projectRoot);
+  const allFiles = [];
+  for (const tf of trackedFiles) {
+    const absPath = path11.join(projectRoot, tf.path);
+    try {
+      const st = await stat3(absPath);
+      if (st.isDirectory()) {
+        const dirEntries = await collectDirectoryFilePaths(absPath, absPath, {
+          projectRoot,
+          gitignoreStack
         });
+        for (const entry of dirEntries) {
+          allFiles.push({
+            relPath: path11.join(tf.path, entry.relPath).replace(/\\/g, "/"),
+            absPath: entry.absPath,
+            mtimeMs: entry.mtimeMs
+          });
+        }
+      } else {
+        allFiles.push({ relPath: tf.path, absPath, mtimeMs: st.mtimeMs });
       }
+    } catch {
       continue;
     }
-    if (!entry.isFile()) {
-      continue;
+  }
+  const filtered = excludePrefixes?.length ? allFiles.filter((entry) => !excludePrefixes.some((prefix) => entry.relPath === prefix || entry.relPath.startsWith(prefix + "/"))) : allFiles;
+  const dirty = [];
+  for (const entry of filtered) {
+    const storedMtime = storedFileData?.mtimes[entry.relPath];
+    const storedHash = storedFileData?.hashes[entry.relPath];
+    if (storedMtime !== void 0 && storedHash !== void 0 && entry.mtimeMs === storedMtime) {
+      fileHashes[entry.relPath] = storedHash;
+    } else {
+      dirty.push(entry);
     }
-    result.push({
-      path: path11.relative(rootDirectoryPath, absoluteChildPath),
-      hash: await hashFile(absoluteChildPath)
-    });
+    fileMtimes[entry.relPath] = entry.mtimeMs;
   }
-  return result;
-}
-async function loadGitignoreMatcher(projectRoot) {
-  if (!projectRoot) {
-    return void 0;
+  const BATCH_SIZE = 256;
+  for (let i = 0; i < dirty.length; i += BATCH_SIZE) {
+    const batch = dirty.slice(i, i + BATCH_SIZE);
+    const hashes = await Promise.all(batch.map((e) => hashFile(e.absPath)));
+    for (let j = 0; j < batch.length; j++) {
+      fileHashes[batch[j].relPath] = hashes[j];
+    }
   }
+  const sorted = Object.entries(fileHashes).sort(([a], [b]) => a.localeCompare(b));
+  const digest = sorted.map(([p, h]) => `${p}:${h}`).join("\n");
+  const canonicalHash = hashString(digest);
+  return { canonicalHash, fileHashes, fileMtimes };
+}
+async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, options) {
+  let stack = options.gitignoreStack ?? [];
   try {
-    const gitignorePath = path11.join(projectRoot, ".gitignore");
-    const gitignoreContent = await readFile12(gitignorePath, "utf-8");
-    const matcher = ignoreFactory();
-    matcher.add(gitignoreContent);
-    return matcher;
+    const localContent = await readFile12(path11.join(directoryPath, ".gitignore"), "utf-8");
+    const localMatcher = ignoreFactory();
+    localMatcher.add(localContent);
+    stack = [...stack, { basePath: directoryPath, matcher: localMatcher }];
   } catch {
-    return void 0;
   }
+  const entries = await readdir5(directoryPath, { withFileTypes: true });
+  const dirs = [];
+  const files = [];
+  for (const entry of entries) {
+    const absoluteChildPath = path11.join(directoryPath, entry.name);
+    if (isIgnoredByStack(absoluteChildPath, stack)) continue;
+    if (entry.isDirectory()) dirs.push(absoluteChildPath);
+    else if (entry.isFile()) files.push(absoluteChildPath);
+  }
+  const [dirResults, fileStats] = await Promise.all([
+    Promise.all(dirs.map((d) => collectDirectoryFilePaths(d, rootDirectoryPath, {
+      projectRoot: options.projectRoot,
+      gitignoreStack: stack
+    }))),
+    Promise.all(files.map(async (f) => {
+      const fileStat = await stat3(f);
+      return {
+        relPath: path11.relative(rootDirectoryPath, f),
+        absPath: f,
+        mtimeMs: fileStat.mtimeMs
+      };
+    }))
+  ]);
+  const result = [];
+  for (const nested of dirResults) result.push(...nested);
+  result.push(...fileStats);
+  return result;
 }
-function isIgnoredPath(candidatePath, projectRoot, matcher) {
-  if (!projectRoot || !matcher) {
-    return false;
+
+// src/core/context-files.ts
+import path12 from "path";
+var STRUCTURAL_RELATION_TYPES2 = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
+function collectTrackedFiles(node, graph) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  const projectRoot = path12.dirname(graph.rootPath);
+  const yggPrefix = path12.relative(projectRoot, graph.rootPath);
+  const yggPrefixNormalized = yggPrefix.split(path12.sep).join("/");
+  const configArtifactKeys = new Set(Object.keys(graph.config.artifacts ?? {}));
+  function addFile(filePath, category) {
+    if (seen.has(filePath)) return;
+    seen.add(filePath);
+    result.push({ path: filePath, category });
   }
-  const relativePath = path11.relative(projectRoot, candidatePath);
-  if (relativePath === "" || relativePath.startsWith("..")) {
-    return false;
+  function graphPath(...segments) {
+    return [yggPrefixNormalized, ...segments].join("/");
   }
-  return matcher.ignores(relativePath) || matcher.ignores(relativePath + "/");
-}
-function hashString(content) {
-  return createHash("sha256").update(content).digest("hex");
-}
-async function perFileHashes(projectRoot, mapping) {
-  const root = path11.resolve(projectRoot);
-  const paths = mapping.paths ?? [];
-  if (paths.length === 0) return [];
-  const result = [];
-  const gitignoreMatcher = await loadGitignoreMatcher(root);
-  for (const p of paths) {
-    const absPath = path11.join(root, p);
-    const st = await stat3(absPath);
-    if (st.isFile()) {
-      result.push({ path: p, hash: await hashFile(absPath) });
-    } else if (st.isDirectory()) {
-      const hashes = await collectDirectoryFileHashes(absPath, absPath, {
-        projectRoot: root,
-        gitignoreMatcher
-      });
-      for (const h of hashes) {
-        result.push({
-          path: path11.join(p, h.path).split(path11.sep).join("/"),
-          hash: h.hash
-        });
+  function addNodeFiles(n) {
+    addFile(graphPath("model", n.path, "node.yaml"), "graph");
+    for (const art of n.artifacts) {
+      if (configArtifactKeys.has(art.filename)) {
+        addFile(graphPath("model", n.path, art.filename), "graph");
       }
     }
   }
-  return result;
-}
-async function hashForMapping(projectRoot, mapping) {
-  const root = path11.resolve(projectRoot);
-  const paths = mapping.paths ?? [];
-  if (paths.length === 0) throw new Error("Invalid mapping for hash: no paths");
-  const pairs = [];
-  for (const p of paths) {
-    const absPath = path11.join(root, p);
-    const st = await stat3(absPath);
-    if (st.isFile()) {
-      pairs.push({ path: p, hash: await hashFile(absPath) });
-    } else if (st.isDirectory()) {
-      const dirHash = await hashPath(absPath, { projectRoot: root });
-      pairs.push({ path: p, hash: dirHash });
+  addNodeFiles(node);
+  const ancestors = collectAncestors(node);
+  for (const ancestor of ancestors) {
+    addNodeFiles(ancestor);
+  }
+  const allAspectIds = /* @__PURE__ */ new Set();
+  for (const id of node.meta.aspects ?? []) {
+    allAspectIds.add(id);
+  }
+  for (const ancestor of ancestors) {
+    for (const id of ancestor.meta.aspects ?? []) {
+      allAspectIds.add(id);
     }
   }
-  const digestInput = pairs.sort((a, b) => a.path.localeCompare(b.path)).map((e) => `${e.path}:${e.hash}`).join("\n");
-  return createHash("sha256").update(digestInput).digest("hex");
+  const participatingFlows = collectParticipatingFlows2(graph, node, ancestors);
+  for (const flow of participatingFlows) {
+    for (const id of flow.aspects ?? []) {
+      allAspectIds.add(id);
+    }
+  }
+  const resolvedAspects = resolveAspects(allAspectIds, graph.aspects);
+  for (const aspect of resolvedAspects) {
+    addFile(graphPath("aspects", aspect.id, "aspect.yaml"), "graph");
+    for (const art of aspect.artifacts) {
+      addFile(graphPath("aspects", aspect.id, art.filename), "graph");
+    }
+  }
+  for (const relation of node.meta.relations ?? []) {
+    if (!STRUCTURAL_RELATION_TYPES2.has(relation.type)) continue;
+    const target = graph.nodes.get(relation.target);
+    if (!target) continue;
+    const structuralFilenames = Object.entries(graph.config.artifacts ?? {}).filter(([, c]) => c.structural_context).map(([filename]) => filename);
+    const structuralArts = structuralFilenames.filter(
+      (filename) => target.artifacts.some((a) => a.filename === filename)
+    );
+    if (structuralArts.length > 0) {
+      for (const filename of structuralArts) {
+        addFile(graphPath("model", target.path, filename), "graph");
+      }
+    } else {
+      for (const art of target.artifacts) {
+        if (configArtifactKeys.has(art.filename)) {
+          addFile(graphPath("model", target.path, art.filename), "graph");
+        }
+      }
+    }
+  }
+  for (const flow of participatingFlows) {
+    addFile(graphPath("flows", flow.path, "flow.yaml"), "graph");
+    for (const art of flow.artifacts) {
+      addFile(graphPath("flows", flow.path, art.filename), "graph");
+    }
+  }
+  const mappingPaths = normalizeMappingPaths(node.meta.mapping);
+  for (const p of mappingPaths) {
+    addFile(p, "source");
+  }
+  return result;
+}
+function collectParticipatingFlows2(graph, node, ancestors) {
+  const paths = /* @__PURE__ */ new Set([node.path, ...ancestors.map((a) => a.path)]);
+  return graph.flows.filter((f) => f.nodes.some((n) => paths.has(n)));
 }
 
 // src/core/drift-detector.ts
 import { access } from "fs/promises";
-import path12 from "path";
+import path13 from "path";
+function getChildMappingExclusions(graph, nodePath) {
+  const node = graph.nodes.get(nodePath);
+  if (!node) return [];
+  const parentMappings = normalizeMappingPaths(node.meta.mapping);
+  if (parentMappings.length === 0) return [];
+  const exclusions = [];
+  for (const [childPath, childNode] of graph.nodes) {
+    if (childPath === nodePath) continue;
+    if (!childPath.startsWith(nodePath + "/")) continue;
+    const childMappings = normalizeMappingPaths(childNode.meta.mapping);
+    for (const cm of childMappings) {
+      for (const pm of parentMappings) {
+        if (cm === pm || cm.startsWith(pm + "/")) {
+          exclusions.push(cm);
+        }
+      }
+    }
+  }
+  return exclusions;
+}
 async function detectDrift(graph, filterNodePath) {
-  const projectRoot = path12.dirname(graph.rootPath);
+  const projectRoot = path13.dirname(graph.rootPath);
   const driftState = await readDriftState(graph.rootPath);
   const entries = [];
   for (const [nodePath, node] of graph.nodes) {
-    if (filterNodePath && nodePath !== filterNodePath) continue;
+    if (filterNodePath && nodePath !== filterNodePath && !nodePath.startsWith(filterNodePath + "/")) continue;
     const mapping = node.meta.mapping;
     if (!mapping) continue;
     const mappingPaths = normalizeMappingPaths(mapping);
@@ -2600,67 +2696,82 @@ async function detectDrift(graph, filterNodePath) {
       const allMissing = await allPathsMissing(projectRoot, mappingPaths);
       entries.push({
         nodePath,
-        mappingPaths,
-        status: allMissing ? "unmaterialized" : "drift",
+        status: allMissing ? "unmaterialized" : "source-drift",
         details: allMissing ? "No drift state recorded, files do not exist" : "No drift state recorded, files exist (run drift-sync after materialization)"
       });
       continue;
     }
-    const storedHash = getCanonicalHash(storedEntry);
-    let status = "ok";
-    let details = "";
-    try {
-      const currentHash = await hashForMapping(projectRoot, mapping);
-      if (currentHash !== storedHash) {
-        status = "drift";
-        const changedFiles = await diagnoseChangedFiles(
-          projectRoot,
-          mapping,
-          getFileHashes(storedEntry)
-        );
-        details = changedFiles.length > 0 ? `Changed files: ${changedFiles.join(", ")}` : "File(s) modified since last sync";
+    const sourceFilesMissing = await allPathsMissing(projectRoot, mappingPaths);
+    if (sourceFilesMissing) {
+      entries.push({
+        nodePath,
+        status: "missing",
+        details: "All source mapping paths are missing"
+      });
+      continue;
+    }
+    const trackedFiles = collectTrackedFiles(node, graph);
+    const excludePrefixes = getChildMappingExclusions(graph, nodePath);
+    const storedFileData = storedEntry.files ? { hashes: storedEntry.files, mtimes: storedEntry.mtimes ?? {} } : void 0;
+    const { canonicalHash, fileHashes } = await hashTrackedFiles(projectRoot, trackedFiles, storedFileData, excludePrefixes);
+    if (canonicalHash === storedEntry.hash) {
+      entries.push({ nodePath, status: "ok" });
+      continue;
+    }
+    const changedFiles = [];
+    const storedFiles = storedEntry.files;
+    for (const [filePath, hash] of Object.entries(fileHashes)) {
+      const storedHash = storedFiles[filePath];
+      if (!storedHash || storedHash !== hash) {
+        changedFiles.push({
+          filePath,
+          category: categorizeFile(filePath, graph.rootPath, projectRoot)
+        });
       }
-    } catch {
-      status = "missing";
-      details = "Mapped path(s) do not exist";
     }
-    entries.push({ nodePath, mappingPaths, status, details });
+    for (const storedPath of Object.keys(storedFiles)) {
+      if (!(storedPath in fileHashes)) {
+        changedFiles.push({
+          filePath: `${storedPath} (deleted)`,
+          category: categorizeFile(storedPath, graph.rootPath, projectRoot)
+        });
+      }
+    }
+    const hasSourceChanges = changedFiles.some((f) => f.category === "source");
+    const hasGraphChanges = changedFiles.some((f) => f.category === "graph");
+    let status;
+    if (hasSourceChanges && hasGraphChanges) {
+      status = "full-drift";
+    } else if (hasGraphChanges) {
+      status = "graph-drift";
+    } else if (hasSourceChanges) {
+      status = "source-drift";
+    } else {
+      status = "source-drift";
+    }
+    const details = changedFiles.length > 0 ? `Changed files: ${changedFiles.map((f) => f.filePath).join(", ")}` : "File(s) modified since last sync";
+    entries.push({ nodePath, status, details, changedFiles });
   }
   return {
     entries,
     totalChecked: entries.length,
     okCount: entries.filter((e) => e.status === "ok").length,
-    driftCount: entries.filter((e) => e.status === "drift").length,
+    sourceDriftCount: entries.filter((e) => e.status === "source-drift").length,
+    graphDriftCount: entries.filter((e) => e.status === "graph-drift").length,
+    fullDriftCount: entries.filter((e) => e.status === "full-drift").length,
     missingCount: entries.filter((e) => e.status === "missing").length,
     unmaterializedCount: entries.filter((e) => e.status === "unmaterialized").length
   };
 }
-async function diagnoseChangedFiles(projectRoot, mapping, storedFileHashes) {
-  try {
-    const currentHashes = await perFileHashes(projectRoot, mapping);
-    if (!storedFileHashes) {
-      return currentHashes.map((h) => h.path).sort();
-    }
-    const changed = [];
-    const storedPaths = new Set(Object.keys(storedFileHashes));
-    for (const { path: filePath, hash } of currentHashes) {
-      const stored = storedFileHashes[filePath];
-      if (!stored || stored !== hash) {
-        changed.push(filePath);
-      }
-      storedPaths.delete(filePath);
-    }
-    for (const removed of storedPaths) {
-      changed.push(`${removed} (deleted)`);
-    }
-    return changed.sort();
-  } catch {
-    return [];
-  }
+function categorizeFile(filePath, _rootPath, projectRoot) {
+  const yggPrefix = path13.relative(projectRoot, _rootPath);
+  const normalizedPrefix = yggPrefix.split(path13.sep).join("/");
+  const normalizedFilePath = filePath.replace(/\\/g, "/");
+  return normalizedFilePath.startsWith(normalizedPrefix) ? "graph" : "source";
 }
 async function allPathsMissing(projectRoot, mappingPaths) {
   for (const mp of mappingPaths) {
-    const absPath = path12.join(projectRoot, mp);
+    const absPath = path13.join(projectRoot, mp);
     try {
       await access(absPath);
       return false;
@@ -2670,82 +2781,53 @@ async function allPathsMissing(projectRoot, mappingPaths) {
   return true;
 }
 async function syncDriftState(graph, nodePath) {
-  const projectRoot = path12.dirname(graph.rootPath);
+  const projectRoot = path13.dirname(graph.rootPath);
   const node = graph.nodes.get(nodePath);
   if (!node) throw new Error(`Node not found: ${nodePath}`);
-  const mapping = node.meta.mapping;
-  if (!mapping) throw new Error(`Node has no mapping: ${nodePath}`);
-  const currentHash = await hashForMapping(projectRoot, mapping);
-  const driftState = await readDriftState(graph.rootPath);
-  const previousEntry = driftState[nodePath];
-  const previousHash = previousEntry ? getCanonicalHash(previousEntry) : void 0;
-  const fileHashes = await perFileHashes(projectRoot, mapping);
-  const files = {};
-  for (const fh of fileHashes) {
-    files[fh.path] = fh.hash;
+  if (!node.meta.mapping) throw new Error(`Node has no mapping: ${nodePath}`);
+  const trackedFiles = collectTrackedFiles(node, graph);
+  const excludePrefixes = getChildMappingExclusions(graph, nodePath);
+  const existingState = await readDriftState(graph.rootPath);
+  const existingEntry = existingState[nodePath];
+  const storedFileData = existingEntry?.files ? { hashes: existingEntry.files, mtimes: existingEntry.mtimes ?? {} } : void 0;
+  const { canonicalHash, fileHashes, fileMtimes } = await hashTrackedFiles(projectRoot, trackedFiles, storedFileData, excludePrefixes);
+  const previousHash = existingEntry?.hash;
+  existingState[nodePath] = { hash: canonicalHash, files: fileHashes, mtimes: fileMtimes };
+  for (const key of Object.keys(existingState)) {
+    if (!graph.nodes.has(key)) {
+      delete existingState[key];
+    }
   }
-  const newEntry = { hash: currentHash, files };
-  driftState[nodePath] = newEntry;
-  await writeDriftState(graph.rootPath, driftState);
-  return { previousHash, currentHash };
+  await writeDriftState(graph.rootPath, existingState);
+  return { previousHash, currentHash: canonicalHash };
 }
 
 // src/cli/drift.ts
 function registerDriftCommand(program2) {
-  program2.command("drift").description("Detect divergence between graph and code").option("--scope <scope>", "Scope: all or node-path (default: all)", "all").action(async (options) => {
+  program2.command("drift").description("Detect divergences between graph and mapped files").option("--scope <scope>", 'Scope: "all" or node path', "all").option("--drifted-only", "Show only nodes with drift (hide ok entries)").option("--limit <n>", "Maximum number of entries to show per section", parseInt).action(async (opts) => {
     try {
       const graph = await loadGraph(process.cwd());
-      const scope = (options.scope ?? "all").trim() || "all";
-      if (scope && scope !== "all" && !graph.nodes.has(scope)) {
-        process.stderr.write(`Error: Node not found: ${scope}
+      const rawScope = (opts.scope ?? "all").trim() || "all";
+      const scope = rawScope === "all" ? "all" : rawScope.replace(/^\.\//, "").replace(/\/+$/, "");
+      if (scope !== "all") {
+        const node = graph.nodes.get(scope);
+        if (!node) {
+          process.stderr.write(`Error: Node not found: ${scope}
 `);
-        process.exit(1);
-      }
-      if (scope && scope !== "all") {
-        const scopedNode = graph.nodes.get(scope);
-        if (!scopedNode.meta.mapping) {
-          process.stderr.write(
-            `Error: Node has no mapping (does not participate in drift detection): ${options.scope}
-`
-          );
-          process.exit(1);
-        }
-      }
-      const scopeNode = scope === "all" ? void 0 : scope;
-      const report = await detectDrift(graph, scopeNode);
-      process.stdout.write("Drift:\n");
-      for (const entry of report.entries) {
-        const paths = entry.mappingPaths.join(", ");
-        switch (entry.status) {
-          case "ok":
-            process.stdout.write(chalk2.green(`  ok       ${entry.nodePath} -> ${paths}
-`));
-            break;
-          case "drift":
-            process.stdout.write(chalk2.red(`  drift    ${entry.nodePath} -> ${paths}
-`));
-            if (entry.details) process.stdout.write(`           ${entry.details}
+          process.exit(1);
+        }
+        const hasAnyMapping = node.meta.mapping || [...graph.nodes.entries()].some(([p, n]) => p.startsWith(scope + "/") && n.meta.mapping);
+        if (!hasAnyMapping) {
+          process.stderr.write(`Error: Node has no mapping: ${scope}
 `);
-            break;
-          case "missing":
-            process.stdout.write(chalk2.yellow(`  missing  ${entry.nodePath} -> ${paths}
-`));
-            break;
-          case "unmaterialized":
-            process.stdout.write(chalk2.dim(`  unmat.   ${entry.nodePath} -> ${paths}
-`));
-            break;
+          process.exit(1);
         }
       }
-      process.stdout.write(
-        `
-Summary: ${report.driftCount} drift, ${report.missingCount} missing, ${report.unmaterializedCount} unmaterialized, ${report.okCount} ok
-`
-      );
-      if (report.driftCount > 0 || report.missingCount > 0 || report.unmaterializedCount > 0) {
-        process.exit(1);
-      }
-      process.exit(0);
+      const scopeNode = scope === "all" ? void 0 : scope;
+      const report = await detectDrift(graph, scopeNode);
+      printReport(report, opts.driftedOnly ?? false, opts.limit);
+      const hasIssues = report.sourceDriftCount > 0 || report.graphDriftCount > 0 || report.fullDriftCount > 0 || report.missingCount > 0 || report.unmaterializedCount > 0;
+      process.exit(hasIssues ? 1 : 0);
     } catch (error) {
       process.stderr.write(`Error: ${error.message}
 `);
@@ -2753,21 +2835,151 @@ Summary: ${report.driftCount} drift, ${report.missingCount} missing, ${report.un
     }
   });
 }
+function printReport(report, driftedOnly, limit) {
+  const sourceEntries = classifyForSection(report.entries, "source", driftedOnly);
+  const graphEntries = classifyForSection(report.entries, "graph", driftedOnly);
+  const sourceShown = limit !== void 0 ? sourceEntries.slice(0, limit) : sourceEntries;
+  const graphShown = limit !== void 0 ? graphEntries.slice(0, limit) : graphEntries;
+  process.stdout.write("Source drift:\n");
+  printSectionEntries(sourceShown, "source");
+  if (limit !== void 0 && sourceEntries.length > limit) {
+    process.stdout.write(chalk2.dim(`  ... ${sourceEntries.length - limit} more (${sourceEntries.length} total)
+`));
+  }
+  process.stdout.write("\nGraph drift:\n");
+  printSectionEntries(graphShown, "graph");
+  if (limit !== void 0 && graphEntries.length > limit) {
+    process.stdout.write(chalk2.dim(`  ... ${graphEntries.length - limit} more (${graphEntries.length} total)
+`));
+  }
+  const parts = [
+    `${report.sourceDriftCount} source-drift`,
+    `${report.graphDriftCount} graph-drift`,
+    `${report.fullDriftCount} full-drift`,
+    `${report.missingCount} missing`,
+    `${report.unmaterializedCount} unmaterialized`
+  ];
+  let summary = `
+Summary: ${parts.join(", ")}`;
+  if (driftedOnly && report.okCount > 0) {
+    summary += ` (${report.okCount} ok hidden)`;
+  } else {
+    summary += `, ${report.okCount} ok`;
+  }
+  process.stdout.write(summary + "\n");
+}
+function classifyForSection(entries, section, driftedOnly) {
+  return entries.filter((entry) => {
+    if (section === "source") {
+      if (entry.status === "graph-drift") return false;
+      if (entry.status === "ok" && driftedOnly) return false;
+      return true;
+    } else {
+      if (entry.status === "source-drift" || entry.status === "missing" || entry.status === "unmaterialized")
+        return false;
+      if (entry.status === "ok" && driftedOnly) return false;
+      return true;
+    }
+  });
+}
+function printSectionEntries(entries, section) {
+  if (entries.length === 0) {
+    process.stdout.write(chalk2.dim("  (none)\n"));
+    return;
+  }
+  for (const entry of entries) {
+    printEntryLine(entry);
+    printChangedFiles(entry, section);
+  }
+}
+function printEntryLine(entry) {
+  const pad = 13;
+  switch (entry.status) {
+    case "ok":
+      process.stdout.write(chalk2.green(`  ${"[ok]".padEnd(pad)}${entry.nodePath}
+`));
+      break;
+    case "source-drift":
+      process.stdout.write(chalk2.red(`  ${"[drift]".padEnd(pad)}${entry.nodePath}
+`));
+      break;
+    case "graph-drift":
+      process.stdout.write(chalk2.magenta(`  ${"[drift]".padEnd(pad)}${entry.nodePath}
+`));
+      break;
+    case "full-drift":
+      process.stdout.write(chalk2.red(`  ${"[drift]".padEnd(pad)}${entry.nodePath}
+`));
+      break;
+    case "missing":
+      process.stdout.write(chalk2.yellow(`  ${"[missing]".padEnd(pad)}${entry.nodePath}
+`));
+      break;
+    case "unmaterialized":
+      process.stdout.write(chalk2.dim(`  ${"[unmat.]".padEnd(pad)}${entry.nodePath}
+`));
+      break;
+  }
+}
+function printChangedFiles(entry, section) {
+  if (!entry.changedFiles || entry.changedFiles.length === 0) return;
+  const indent = " ".repeat(15);
+  const relevantFiles = entry.changedFiles.filter((f) => {
+    if (section === "source") return f.category === "source";
+    return f.category === "graph";
+  });
+  for (const file of relevantFiles) {
+    process.stdout.write(chalk2.dim(`${indent}${file.filePath}  (changed)
+`));
+  }
+}
 
 // src/cli/drift-sync.ts
 import chalk3 from "chalk";
 function registerDriftSyncCommand(program2) {
-  program2.command("drift-sync").description("Record current file hash after resolving drift").requiredOption("--node <path>", "Node path to sync").action(async (options) => {
+  program2.command("drift-sync").description("Record current file hash after resolving drift").option("--node <path>", "Node path to sync").option("--recursive", "Also sync all descendant nodes").option("--all", "Sync all nodes with mappings").action(async (options) => {
     try {
+      if (!options.node && !options.all) {
+        process.stderr.write("Error: either '--node <path>' or '--all' is required\n");
+        process.exit(1);
+      }
       const graph = await loadGraph(process.cwd());
-      const nodePath = options.node.trim().replace(/\/$/, "");
-      const { previousHash, currentHash } = await syncDriftState(graph, nodePath);
-      process.stdout.write(chalk3.green(`Synchronized: ${nodePath}
+      let nodesToSync;
+      if (options.all) {
+        nodesToSync = [...graph.nodes.entries()].filter(([, n]) => normalizeMappingPaths(n.meta.mapping).length > 0).map(([p]) => p).sort();
+      } else {
+        const nodePath = options.node.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+        if (!graph.nodes.has(nodePath)) {
+          await syncDriftState(graph, nodePath);
+          return;
+        }
+        nodesToSync = [nodePath];
+        if (options.recursive) {
+          const prefix = nodePath + "/";
+          for (const [p] of graph.nodes) {
+            if (p.startsWith(prefix)) {
+              nodesToSync.push(p);
+            }
+          }
+          nodesToSync.sort();
+        }
+      }
+      for (const np of nodesToSync) {
+        const node = graph.nodes.get(np);
+        if (normalizeMappingPaths(node.meta.mapping).length === 0) {
+          if (!options.all && !options.recursive && np === options.node) {
+            await syncDriftState(graph, np);
+          }
+          continue;
+        }
+        const { previousHash, currentHash } = await syncDriftState(graph, np);
+        process.stdout.write(chalk3.green(`Synchronized: ${np}
 `));
-      process.stdout.write(
-        `  Hash: ${previousHash ? previousHash.slice(0, 8) : "none"} -> ${currentHash.slice(0, 8)}
+        process.stdout.write(
+          `  Hash: ${previousHash ? previousHash.slice(0, 8) : "none"} -> ${currentHash.slice(0, 8)}
 `
-      );
+        );
+      }
     } catch (error) {
       process.stderr.write(`Error: ${error.message}
 `);
@@ -2790,20 +3002,40 @@ function registerStatusCommand(program2) {
       let structuralRelations = 0;
       let eventRelations = 0;
       const structuralTypes = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
+      let maxRelCount = 0;
+      let maxRelNode = "";
       for (const node of graph.nodes.values()) {
+        const relCount = (node.meta.relations ?? []).length;
+        if (relCount > maxRelCount) {
+          maxRelCount = relCount;
+          maxRelNode = node.path;
+        }
         for (const rel of node.meta.relations ?? []) {
           if (structuralTypes.has(rel.type)) structuralRelations += 1;
           else eventRelations += 1;
         }
       }
       const flowCount = graph.flows.length;
-      const knowledgeCount = graph.knowledge.length;
       const drift = await detectDrift(graph);
       const validation = await validate(graph, "all");
       const errorCount = validation.issues.filter((issue) => issue.severity === "error").length;
       const warningCount = validation.issues.filter(
         (issue) => issue.severity === "warning"
       ).length;
+      const configuredArtifactTypes = Object.keys(graph.config.artifacts ?? {});
+      const totalSlots = graph.nodes.size * configuredArtifactTypes.length;
+      let filledSlots = 0;
+      let mappedNodeCount = 0;
+      for (const node of graph.nodes.values()) {
+        const allowed = new Set(configuredArtifactTypes);
+        filledSlots += node.artifacts.filter((a) => allowed.has(a.filename)).length;
+        if (normalizeMappingPaths(node.meta.mapping).length > 0) mappedNodeCount++;
+      }
+      let aspectCoveredNodes = 0;
+      for (const node of graph.nodes.values()) {
+        const effective = collectEffectiveAspectIds(graph, node.path);
+        if (effective.size > 0) aspectCoveredNodes++;
+      }
       process.stdout.write(`Graph: ${graph.config.name}
 `);
       const pluralize = (word, count) => count === 1 ? word : word.endsWith("y") ? word.slice(0, -1) + "ies" : word + "s";
@@ -2817,15 +3049,37 @@ function registerStatusCommand(program2) {
 `
       );
       process.stdout.write(
-        `Aspects: ${graph.aspects.length}    Flows: ${flowCount}    Knowledge: ${knowledgeCount}
+        `Aspects: ${graph.aspects.length}    Flows: ${flowCount}
 `
       );
       process.stdout.write(
-        `Drift: ${drift.driftCount} drift, ${drift.missingCount} missing, ${drift.unmaterializedCount} unmaterialized, ${drift.okCount} ok
+        `Drift: ${drift.sourceDriftCount} source-drift, ${drift.graphDriftCount} graph-drift, ${drift.fullDriftCount} full-drift, ${drift.missingCount} missing, ${drift.unmaterializedCount} unmaterialized, ${drift.okCount} ok
 `
       );
       process.stdout.write(`Validation: ${errorCount} errors, ${warningCount} warnings
 `);
+      const fillPct = totalSlots > 0 ? Math.round(filledSlots / totalSlots * 100) : 0;
+      const totalRelations = structuralRelations + eventRelations;
+      const avgRel = graph.nodes.size > 0 ? (totalRelations / graph.nodes.size).toFixed(1) : "0";
+      process.stdout.write(`
+Quality:
+`);
+      process.stdout.write(
+        `  Artifacts: ${filledSlots}/${totalSlots} slots filled (${fillPct}%) \u2014 ${configuredArtifactTypes.length} types \xD7 ${graph.nodes.size} nodes
+`
+      );
+      process.stdout.write(
+        `  Relations: avg ${avgRel}/node, max ${maxRelCount}${maxRelNode ? ` (${maxRelNode})` : ""}
+`
+      );
+      process.stdout.write(
+        `  Mapping: ${mappedNodeCount}/${graph.nodes.size} nodes mapped to source
+`
+      );
+      process.stdout.write(
+        `  Aspects: ${aspectCoveredNodes}/${graph.nodes.size} nodes have aspect coverage
+`
+      );
     } catch (error) {
       process.stderr.write(`Error: ${error.message}
 `);
@@ -2842,10 +3096,10 @@ function registerTreeCommand(program2) {
       let roots;
       let showProjectName;
       if (options.root?.trim()) {
-        const path16 = options.root.trim().replace(/\/$/, "");
-        const node = graph.nodes.get(path16);
+        const path18 = options.root.trim().replace(/\/$/, "");
+        const node = graph.nodes.get(path18);
         if (!node) {
-          process.stderr.write(`Error: path '${path16}' not found
+          process.stderr.write(`Error: path '${path18}' not found
 `);
           process.exit(1);
         }
@@ -2873,7 +3127,7 @@ function printNode(node, prefix, isLast, depth, maxDepth) {
   const connector = isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
   const name = node.path.split("/").pop() ?? node.path;
   const type = `[${node.meta.type}]`;
-  const tags = node.meta.tags?.length ? ` tags:${node.meta.tags.join(",")}` : "";
+  const tags = node.meta.aspects?.length ? ` aspects:${node.meta.aspects.join(",")}` : "";
   const blackbox = node.meta.blackbox ? " \u25A0 blackbox" : "";
   const relationCount = node.meta.relations?.length ?? 0;
   process.stdout.write(
@@ -2889,6 +3143,8 @@ function printNode(node, prefix, isLast, depth, maxDepth) {
 }
 
 // src/cli/owner.ts
+import path14 from "path";
+import { access as access2 } from "fs/promises";
 function normalizeForMatch(inputPath) {
   return inputPath.replace(/\\/g, "/").replace(/\/+$/, "");
 }
@@ -2913,12 +3169,28 @@ function findOwner(graph, projectRoot, rawPath) {
 function registerOwnerCommand(program2) {
   program2.command("owner").description("Find which graph node owns a source file").requiredOption("--file <path>", "File path (relative to repository root)").action(async (options) => {
     try {
-      const projectRoot = process.cwd();
-      const graph = await loadGraph(projectRoot);
-      const result = findOwner(graph, projectRoot, options.file);
+      const cwd = process.cwd();
+      const graph = await loadGraph(cwd);
+      const repoRoot = projectRootFromGraph(graph.rootPath);
+      const rawPath = options.file.trim();
+      const absolute = path14.resolve(cwd, rawPath);
+      const repoRelative = path14.relative(repoRoot, absolute).split(path14.sep).join("/");
+      const result = findOwner(graph, repoRoot, repoRelative);
       if (!result.nodePath) {
-        process.stdout.write(`${result.file} -> no graph coverage
+        const absPath = path14.resolve(repoRoot, result.file);
+        let exists = true;
+        try {
+          await access2(absPath);
+        } catch {
+          exists = false;
+        }
+        if (exists) {
+          process.stdout.write(`${result.file} -> no graph coverage
 `);
+        } else {
+          process.stdout.write(`${result.file} -> no graph coverage (file not found)
+`);
+        }
       } else {
         process.stdout.write(`${result.file} -> ${result.nodePath}
 `);
@@ -2932,13 +3204,13 @@ function registerOwnerCommand(program2) {
 }
 
 // src/core/dependency-resolver.ts
-import { execSync as execSync2 } from "child_process";
-import path13 from "path";
-var STRUCTURAL_RELATION_TYPES2 = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
+import { execSync } from "child_process";
+import path15 from "path";
+var STRUCTURAL_RELATION_TYPES3 = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
 var EVENT_RELATION_TYPES2 = /* @__PURE__ */ new Set(["emits", "listens"]);
 function filterRelationType(relType, filter) {
   if (filter === "all") return true;
-  if (filter === "structural") return STRUCTURAL_RELATION_TYPES2.has(relType);
+  if (filter === "structural") return STRUCTURAL_RELATION_TYPES3.has(relType);
   if (filter === "event") return EVENT_RELATION_TYPES2.has(relType);
   return false;
 }
@@ -2993,7 +3265,7 @@ function registerDepsCommand(program2) {
     try {
       const graph = await loadGraph(process.cwd());
       const typeFilter = options.type === "structural" || options.type === "event" || options.type === "all" ? options.type : "all";
-      const nodePath = options.node.trim().replace(/\/$/, "");
+      const nodePath = options.node.trim().replace(/^\.\//, "").replace(/\/+$/, "");
       const text = formatDependencyTree(graph, nodePath, {
         depth: options.depth,
         relationType: typeFilter
@@ -3010,24 +3282,24 @@ function registerDepsCommand(program2) {
 // src/core/graph-from-git.ts
 import { mkdtemp, rm } from "fs/promises";
 import { tmpdir } from "os";
-import path14 from "path";
-import { execSync as execSync3 } from "child_process";
+import path16 from "path";
+import { execSync as execSync2 } from "child_process";
 async function loadGraphFromRef(projectRoot, ref = "HEAD") {
   const yggPath = ".yggdrasil";
   let tmpDir = null;
   try {
-    execSync3(`git rev-parse ${ref}`, { cwd: projectRoot, stdio: "pipe" });
+    execSync2(`git rev-parse ${ref}`, { cwd: projectRoot, stdio: "pipe" });
   } catch {
     return null;
   }
   try {
-    tmpDir = await mkdtemp(path14.join(tmpdir(), "ygg-git-"));
-    const archivePath = path14.join(tmpDir, "archive.tar");
-    execSync3(`git archive ${ref} ${yggPath} -o "${archivePath}"`, {
+    tmpDir = await mkdtemp(path16.join(tmpdir(), "ygg-git-"));
+    const archivePath = path16.join(tmpDir, "archive.tar");
+    execSync2(`git archive ${ref} ${yggPath} -o "${archivePath}"`, {
       cwd: projectRoot,
       stdio: "pipe"
     });
-    execSync3(`tar -xf "${archivePath}" -C "${tmpDir}"`, { stdio: "pipe" });
+    execSync2(`tar -xf "${archivePath}" -C "${tmpDir}"`, { stdio: "pipe" });
     const graph = await loadGraph(tmpDir);
     return graph;
   } catch {
@@ -3069,14 +3341,14 @@ function collectReverseDependents(graph, targetNode) {
   }
   return {
     direct,
-    transitive: [...seen].sort(),
+    allDependents: [...seen].sort(),
     reverse,
     relationFrom
   };
 }
-function buildTransitiveChains(targetNode, direct, transitive, reverse) {
+function buildTransitiveChains(targetNode, direct, allDependents, reverse) {
   const directSet = new Set(direct);
-  const transitiveOnly = transitive.filter((t) => !directSet.has(t));
+  const transitiveOnly = allDependents.filter((t) => !directSet.has(t));
   if (transitiveOnly.length === 0) return [];
   const parent = /* @__PURE__ */ new Map();
   const queue = [targetNode];
@@ -3092,164 +3364,391 @@ function buildTransitiveChains(targetNode, direct, transitive, reverse) {
   }
   const chains = [];
   for (const node of transitiveOnly) {
-    const path16 = [];
+    const path18 = [];
     let current = node;
     while (current) {
-      path16.unshift(current);
+      path18.unshift(current);
       current = parent.get(current);
     }
-    if (path16.length >= 2) {
-      chains.push(path16.map((p) => `<- ${p}`).join(" "));
+    if (path18.length >= 3) {
+      chains.push(path18.slice(1).map((p) => `<- ${p}`).join(" "));
     }
   }
   return chains.sort();
 }
-function registerImpactCommand(program2) {
-  program2.command("impact").description("Show reverse dependency impact for a node").requiredOption("--node <path>", "Node path relative to .yggdrasil/model/").option("--simulate", "Simulate context package impact (compare HEAD vs current)").action(async (options) => {
+function collectDescendants(graph, nodePath) {
+  const node = graph.nodes.get(nodePath);
+  if (!node) return [];
+  const result = [];
+  const stack = [...node.children];
+  while (stack.length > 0) {
+    const child = stack.pop();
+    result.push(child.path);
+    stack.push(...child.children);
+  }
+  return result.sort();
+}
+async function runSimulation(graph, nodePaths, targetNodePath) {
+  const budget = graph.config.quality?.context_budget ?? { warning: 1e4, error: 2e4 };
+  process.stdout.write("\nChanges in context packages:\n\n");
+  const baselineGraph = await loadGraphFromRef(process.cwd(), "HEAD");
+  const driftReport = await detectDrift(graph);
+  const driftByNode = new Map(driftReport.entries.map((e) => [e.nodePath, e]));
+  for (const dep of nodePaths) {
     try {
-      const graph = await loadGraph(process.cwd());
-      const nodePath = options.node.trim().replace(/\/$/, "");
-      if (!graph.nodes.has(nodePath)) {
-        process.stderr.write(`Node not found: ${nodePath}
-`);
-        process.exit(1);
+      const pkg2 = await buildContext(graph, dep);
+      const status = pkg2.tokenCount >= budget.error ? "error" : pkg2.tokenCount >= budget.warning ? "warning" : "ok";
+      let baselineTokens = null;
+      if (baselineGraph?.nodes.has(dep)) {
+        try {
+          const baselinePkg = await buildContext(baselineGraph, dep);
+          baselineTokens = baselinePkg.tokenCount;
+        } catch {
+        }
       }
-      const { direct, transitive, reverse, relationFrom } = collectReverseDependents(
-        graph,
-        nodePath
+      const hasDepOnTarget = targetNodePath && graph.nodes.get(dep)?.meta.relations?.some(
+        (r) => r.target === targetNodePath && STRUCTURAL_TYPES.has(r.type)
       );
-      const chains = buildTransitiveChains(nodePath, direct, transitive, reverse);
-      const flows = [];
-      for (const flow of graph.flows) {
-        if (flow.nodes.includes(nodePath)) {
-          flows.push(flow.name);
+      const changedLine = hasDepOnTarget ? `  + Changed dependency interface: ${targetNodePath}
+` : "";
+      const budgetLine = baselineTokens !== null ? `  Budget: ${baselineTokens} -> ${pkg2.tokenCount} tokens (${status})
+` : `  Budget: ${pkg2.tokenCount} tokens (${status})
+`;
+      const driftEntry = driftByNode.get(dep);
+      const driftLine = driftEntry && driftEntry.status !== "ok" ? `  Mapped files (on-disk): ${driftEntry.status}${driftEntry.details ? ` (${driftEntry.details})` : ""}
+` : driftEntry ? `  Mapped files (on-disk): ok
+` : "";
+      process.stdout.write(`${dep}:
+${changedLine}${budgetLine}${driftLine}
+`);
+    } catch {
+      process.stdout.write(`${dep}:
+  failed to build context
+
+`);
+    }
+  }
+}
+async function handleAspectImpact(graph, aspectId, simulate) {
+  const aspect = graph.aspects.find((a) => a.id === aspectId);
+  if (!aspect) {
+    process.stderr.write(`Aspect not found: ${aspectId}
+`);
+    process.exit(1);
+  }
+  const affected = [];
+  for (const [nodePath] of graph.nodes) {
+    const effective = collectEffectiveAspectIds(graph, nodePath);
+    if (effective.has(aspectId)) {
+      const node = graph.nodes.get(nodePath);
+      const ownAspects = new Set(node.meta.aspects ?? []);
+      if (ownAspects.has(aspectId)) {
+        affected.push({ path: nodePath, source: "own" });
+      } else {
+        let fromHierarchy = false;
+        let anc = node.parent;
+        while (anc) {
+          if ((anc.meta.aspects ?? []).includes(aspectId)) {
+            fromHierarchy = true;
+            break;
+          }
+          anc = anc.parent;
         }
-      }
-      const aspectsInScope = [];
-      const targetNode = graph.nodes.get(nodePath);
-      const targetTags = new Set(targetNode.meta.tags ?? []);
-      for (const aspect of graph.aspects) {
-        if (targetTags.has(aspect.tag)) {
-          aspectsInScope.push(aspect.name);
+        if (fromHierarchy) {
+          affected.push({ path: nodePath, source: `hierarchy from ${anc.path}` });
+        } else {
+          const ancestorPaths = /* @__PURE__ */ new Set([nodePath, ...collectAncestors(node).map((a) => a.path)]);
+          const flow = graph.flows.find(
+            (f) => (f.aspects ?? []).includes(aspectId) && f.nodes.some((n) => ancestorPaths.has(n))
+          );
+          affected.push({ path: nodePath, source: flow ? `flow: ${flow.name}` : "implied" });
         }
       }
-      const knowledgeInScope = [];
-      for (const k of graph.knowledge) {
-        if (k.scope === "global") {
-          knowledgeInScope.push(k.path);
-          continue;
+    }
+  }
+  affected.sort((a, b) => a.path.localeCompare(b.path));
+  const propagatingFlows = graph.flows.filter((f) => (f.aspects ?? []).includes(aspectId)).map((f) => f.name);
+  const impliedBy = graph.aspects.filter((a) => (a.implies ?? []).includes(aspectId)).map((a) => a.id);
+  const implies = aspect.implies ?? [];
+  process.stdout.write(`Impact of changes in aspect ${aspectId}:
+
+`);
+  process.stdout.write(`Affected nodes (${affected.length}):
+`);
+  if (affected.length === 0) {
+    process.stdout.write("  (none)\n");
+  } else {
+    for (const { path: p, source } of affected) {
+      process.stdout.write(`  ${p} (${source})
+`);
+    }
+  }
+  process.stdout.write(
+    `
+Flows propagating this aspect: ${propagatingFlows.length > 0 ? propagatingFlows.join(", ") : "(none)"}
+`
+  );
+  process.stdout.write(`Implied by: ${impliedBy.length > 0 ? impliedBy.join(", ") : "(none)"}
+`);
+  process.stdout.write(`Implies: ${implies.length > 0 ? implies.join(", ") : "(none)"}
+`);
+  process.stdout.write(`
+Total scope: ${affected.length} nodes, ${propagatingFlows.length} flows
+`);
+  if (simulate && affected.length > 0) {
+    await runSimulation(
+      graph,
+      affected.map((a) => a.path),
+      null
+    );
+  }
+}
+async function handleFlowImpact(graph, flowName, simulate) {
+  const flow = graph.flows.find((f) => f.name === flowName || f.path === flowName);
+  if (!flow) {
+    process.stderr.write(`Flow not found: ${flowName}
+`);
+    process.exit(1);
+  }
+  const participants = /* @__PURE__ */ new Set();
+  for (const nodePath of flow.nodes) {
+    if (graph.nodes.has(nodePath)) {
+      participants.add(nodePath);
+      for (const desc of collectDescendants(graph, nodePath)) {
+        participants.add(desc);
+      }
+    }
+  }
+  const sorted = [...participants].sort();
+  const flowAspects = flow.aspects ?? [];
+  process.stdout.write(`Impact of changes in flow ${flow.name}:
+
+`);
+  process.stdout.write("Participants:\n");
+  if (sorted.length === 0) {
+    process.stdout.write("  (none)\n");
+  } else {
+    for (const p of sorted) {
+      const isDeclared = flow.nodes.includes(p);
+      const suffix = isDeclared ? "" : " (descendant)";
+      process.stdout.write(`  ${p}${suffix}
+`);
+    }
+  }
+  process.stdout.write(
+    `
+Flow aspects: ${flowAspects.length > 0 ? flowAspects.join(", ") : "(none)"}
+`
+  );
+  process.stdout.write(`
+Total scope: ${sorted.length} nodes
+`);
+  if (simulate && sorted.length > 0) {
+    await runSimulation(graph, sorted, null);
+  }
+}
+function registerImpactCommand(program2) {
+  program2.command("impact").description("Show reverse dependency impact for a node, aspect, or flow").option("--node <path>", "Node path relative to .yggdrasil/model/").option("--aspect <id>", "Aspect id (directory path under aspects/)").option("--flow <name>", "Flow name (directory name under flows/)").option("--simulate", "Simulate context package impact (compare HEAD vs current)").action(
+    async (options) => {
+      try {
+        const modeCount = [options.node, options.aspect, options.flow].filter(Boolean).length;
+        if (modeCount === 0) {
+          process.stderr.write(
+            "Error: one of --node, --aspect, or --flow is required\n"
+          );
+          process.exit(1);
+        }
+        if (modeCount > 1) {
+          process.stderr.write(
+            "Error: --node, --aspect, and --flow are mutually exclusive\n"
+          );
+          process.exit(1);
+        }
+        const graph = await loadGraph(process.cwd());
+        if (options.aspect) {
+          await handleAspectImpact(graph, options.aspect.trim(), options.simulate);
+          return;
+        }
+        if (options.flow) {
+          await handleFlowImpact(graph, options.flow.trim(), options.simulate);
+          return;
         }
-        if (typeof k.scope === "object" && "tags" in k.scope) {
-          if (k.scope.tags.some((t) => targetTags.has(t))) {
-            knowledgeInScope.push(k.path);
+        const nodePath = options.node.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+        if (!graph.nodes.has(nodePath)) {
+          process.stderr.write(`Node not found: ${nodePath}
+`);
+          process.exit(1);
+        }
+        const { direct, allDependents, reverse, relationFrom } = collectReverseDependents(
+          graph,
+          nodePath
+        );
+        const chains = buildTransitiveChains(nodePath, direct, allDependents, reverse);
+        const flows = [];
+        for (const flow of graph.flows) {
+          if (flow.nodes.includes(nodePath)) {
+            flows.push(flow.name);
           }
-          continue;
         }
-        if (typeof k.scope === "object" && "nodes" in k.scope) {
-          if (k.scope.nodes.includes(nodePath)) {
-            knowledgeInScope.push(k.path);
+        const targetEffective = collectEffectiveAspectIds(graph, nodePath);
+        const aspectsInScope = [];
+        for (const aspect of graph.aspects) {
+          if (targetEffective.has(aspect.id)) {
+            aspectsInScope.push(aspect.name);
           }
         }
-      }
-      const budget = graph.config.quality?.context_budget ?? { warning: 1e4, error: 2e4 };
-      process.stdout.write(`Impact of changes in ${nodePath}:
+        process.stdout.write(`Impact of changes in ${nodePath}:
 
 `);
-      process.stdout.write("Directly dependent:\n");
-      if (direct.length === 0) {
-        process.stdout.write("  (none)\n");
-      } else {
-        for (const dep of direct) {
-          const rel = relationFrom.get(`${dep}->${nodePath}`);
-          const annot = rel?.consumes?.length ? ` (${rel.type}, you consume: ${rel.consumes.join(", ")})` : rel ? ` (${rel.type})` : "";
-          process.stdout.write(`  <- ${dep}${annot}
+        process.stdout.write("Directly dependent:\n");
+        if (direct.length === 0) {
+          process.stdout.write("  (none)\n");
+        } else {
+          for (const dep of direct) {
+            const rel = relationFrom.get(`${dep}->${nodePath}`);
+            const annot = rel?.consumes?.length ? ` (${rel.type}, you consume: ${rel.consumes.join(", ")})` : rel ? ` (${rel.type})` : "";
+            process.stdout.write(`  <- ${dep}${annot}
 `);
+          }
         }
-      }
-      process.stdout.write("\nTransitively dependent:\n");
-      if (chains.length === 0) {
-        process.stdout.write("  (none)\n");
-      } else {
-        for (const chain of chains) {
-          process.stdout.write(`  ${chain}
+        process.stdout.write("\nTransitively dependent:\n");
+        if (chains.length === 0) {
+          process.stdout.write("  (none)\n");
+        } else {
+          for (const chain of chains) {
+            process.stdout.write(`  ${chain}
 `);
+          }
         }
-      }
-      process.stdout.write(`
-Flows: ${flows.length > 0 ? flows.join(", ") : "(none)"}
+        const descendants = collectDescendants(graph, nodePath);
+        if (descendants.length > 0) {
+          process.stdout.write("\nDescendants (hierarchy impact):\n");
+          for (const desc of descendants) {
+            process.stdout.write(`  ${desc}
 `);
-      process.stdout.write(
-        `Aspects (scope covers node): ${aspectsInScope.length > 0 ? aspectsInScope.join(", ") : "(none)"}
-`
-      );
-      process.stdout.write(
-        `Knowledge (scope covers node): ${knowledgeInScope.length > 0 ? knowledgeInScope.join(", ") : "(none)"}
+          }
+        }
+        process.stdout.write(
+          `
+Flows: ${flows.length > 0 ? flows.join(", ") : "(none)"}
 `
-      );
-      process.stdout.write(
-        `
-Total scope: ${transitive.length} nodes, ${flows.length} flows, ${aspectsInScope.length} aspects, ${knowledgeInScope.length} knowledge
+        );
+        process.stdout.write(
+          `Aspects (scope covers node): ${aspectsInScope.length > 0 ? aspectsInScope.join(", ") : "(none)"}
 `
-      );
-      if (options.simulate && transitive.length > 0) {
-        process.stdout.write("\nChanges in context packages:\n\n");
-        const baselineGraph = await loadGraphFromRef(process.cwd(), "HEAD");
-        const driftReport = await detectDrift(graph);
-        const driftByNode = new Map(driftReport.entries.map((e) => [e.nodePath, e]));
-        for (const dep of transitive) {
-          try {
-            const pkg = await buildContext(graph, dep);
-            const status = pkg.tokenCount >= budget.error ? "error" : pkg.tokenCount >= budget.warning ? "warning" : "ok";
-            let baselineTokens = null;
-            if (baselineGraph?.nodes.has(dep)) {
-              try {
-                const baselinePkg = await buildContext(baselineGraph, dep);
-                baselineTokens = baselinePkg.tokenCount;
-              } catch {
-              }
+        );
+        const coAspectNodes = [];
+        if (targetEffective.size > 0) {
+          for (const [p] of graph.nodes) {
+            if (p === nodePath) continue;
+            const nodeEffective = collectEffectiveAspectIds(graph, p);
+            const shared = [...targetEffective].filter((id) => nodeEffective.has(id));
+            if (shared.length > 0) {
+              coAspectNodes.push({ path: p, shared });
             }
-            const hasDepOnTarget = graph.nodes.get(dep)?.meta.relations?.some(
-              (r) => r.target === nodePath && STRUCTURAL_TYPES.has(r.type)
-            );
-            const changedLine = hasDepOnTarget ? `  + Changed dependency interface: ${nodePath}
-` : "";
-            const budgetLine = baselineTokens !== null ? `  Budget: ${baselineTokens} -> ${pkg.tokenCount} tokens (${status})
-` : `  Budget: ${pkg.tokenCount} tokens (${status})
-`;
-            const driftEntry = driftByNode.get(dep);
-            const driftLine = driftEntry && driftEntry.status !== "ok" ? `  Mapped files (on-disk): ${driftEntry.status}${driftEntry.details ? ` (${driftEntry.details})` : ""}
-` : driftEntry ? `  Mapped files (on-disk): ok
-` : "";
-            process.stdout.write(`${dep}:
-${changedLine}${budgetLine}${driftLine}
-`);
-          } catch {
-            process.stdout.write(`${dep}:
-  failed to build context
-
+          }
+        }
+        if (coAspectNodes.length > 0) {
+          process.stdout.write("Nodes sharing aspects:\n");
+          for (const { path: p, shared } of coAspectNodes.sort(
+            (a, b) => a.path.localeCompare(b.path)
+          )) {
+            process.stdout.write(`  ${p} (${shared.join(", ")})
 `);
           }
         }
+        const allAffected = /* @__PURE__ */ new Set([...allDependents, ...descendants]);
+        process.stdout.write(
+          `
+Total scope: ${allAffected.size} nodes, ${flows.length} flows, ${aspectsInScope.length} aspects
+`
+        );
+        if (options.simulate && allAffected.size > 0) {
+          await runSimulation(graph, allAffected, nodePath);
+        }
+      } catch (error) {
+        process.stderr.write(`Error: ${error.message}
+`);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/cli/aspects.ts
+import { stringify as yamlStringify } from "yaml";
+function registerAspectsCommand(program2) {
+  program2.command("aspects").description("List aspects with metadata (YAML output)").action(async () => {
+    try {
+      const yggRoot = await findYggRoot(process.cwd());
+      const graph = await loadGraph(yggRoot);
+      const output = graph.aspects.sort((a, b) => a.id.localeCompare(b.id)).map((aspect) => {
+        const entry = { id: aspect.id, name: aspect.name };
+        if (aspect.description) entry.description = aspect.description;
+        if (aspect.implies && aspect.implies.length > 0) entry.implies = aspect.implies;
+        return entry;
+      });
+      process.stdout.write(yamlStringify(output));
+    } catch (error) {
+      const err = error;
+      if (err.code === "ENOENT") {
+        process.stderr.write(
+          `Error: No .yggdrasil/ directory found. Run 'yg init' first.
+`
+        );
+      } else {
+        process.stderr.write(`Error: ${error.message}
+`);
       }
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/flows.ts
+import { stringify as yamlStringify2 } from "yaml";
+function registerFlowsCommand(program2) {
+  program2.command("flows").description("List flows with metadata (YAML output)").action(async () => {
+    try {
+      const yggRoot = await findYggRoot(process.cwd());
+      const graph = await loadGraph(yggRoot);
+      const output = graph.flows.sort((a, b) => a.name.localeCompare(b.name)).map((flow) => {
+        const entry = {
+          name: flow.name,
+          participants: flow.nodes.length,
+          nodes: flow.nodes.sort()
+        };
+        if (flow.aspects && flow.aspects.length > 0) entry.aspects = flow.aspects;
+        return entry;
+      });
+      process.stdout.write(yamlStringify2(output));
     } catch (error) {
-      process.stderr.write(`Error: ${error.message}
+      const err = error;
+      if (err.code === "ENOENT") {
+        process.stderr.write(
+          `Error: No .yggdrasil/ directory found. Run 'yg init' first.
+`
+        );
+      } else {
+        process.stderr.write(`Error: ${error.message}
 `);
+      }
       process.exit(1);
     }
   });
 }
 
 // src/io/journal-store.ts
-import { readFile as readFile13, writeFile as writeFile4, mkdir as mkdir3, rename, access as access2 } from "fs/promises";
-import { parse as parseYaml8, stringify as stringifyYaml2 } from "yaml";
-import path15 from "path";
+import { readFile as readFile13, writeFile as writeFile4, mkdir as mkdir3, rename, access as access3 } from "fs/promises";
+import { parse as parseYaml6, stringify as stringifyYaml } from "yaml";
+import path17 from "path";
 var JOURNAL_FILE = ".journal.yaml";
 var ARCHIVE_DIR = "journals-archive";
 async function readJournal(yggRoot) {
-  const filePath = path15.join(yggRoot, JOURNAL_FILE);
+  const filePath = path17.join(yggRoot, JOURNAL_FILE);
   try {
     const content = await readFile13(filePath, "utf-8");
-    const raw = parseYaml8(content);
+    const raw = parseYaml6(content);
     const entries = raw.entries ?? [];
     return Array.isArray(entries) ? entries : [];
   } catch {
@@ -3261,26 +3760,26 @@ async function appendJournalEntry(yggRoot, note, target) {
   const at = (/* @__PURE__ */ new Date()).toISOString();
   const entry = target ? { at, target, note } : { at, note };
   entries.push(entry);
-  const filePath = path15.join(yggRoot, JOURNAL_FILE);
-  const content = stringifyYaml2({ entries });
+  const filePath = path17.join(yggRoot, JOURNAL_FILE);
+  const content = stringifyYaml({ entries });
   await writeFile4(filePath, content, "utf-8");
   return entry;
 }
 async function archiveJournal(yggRoot) {
-  const journalPath = path15.join(yggRoot, JOURNAL_FILE);
+  const journalPath = path17.join(yggRoot, JOURNAL_FILE);
   try {
-    await access2(journalPath);
+    await access3(journalPath);
   } catch {
     return null;
   }
   const entries = await readJournal(yggRoot);
   if (entries.length === 0) return null;
-  const archiveDir = path15.join(yggRoot, ARCHIVE_DIR);
+  const archiveDir = path17.join(yggRoot, ARCHIVE_DIR);
   await mkdir3(archiveDir, { recursive: true });
   const now = /* @__PURE__ */ new Date();
   const timestamp = `${now.getUTCFullYear()}${String(now.getUTCMonth() + 1).padStart(2, "0")}${String(now.getUTCDate()).padStart(2, "0")}-${String(now.getUTCHours()).padStart(2, "0")}${String(now.getUTCMinutes()).padStart(2, "0")}${String(now.getUTCSeconds()).padStart(2, "0")}`;
   const archiveName = `.journal.${timestamp}.yaml`;
-  const archivePath = path15.join(archiveDir, archiveName);
+  const archivePath = path17.join(archiveDir, archiveName);
   await rename(journalPath, archivePath);
   return { archiveName, entryCount: entries.length };
 }
@@ -3356,9 +3855,93 @@ function registerJournalArchiveCommand(program2) {
   });
 }
 
+// src/cli/preflight.ts
+function registerPreflightCommand(program2) {
+  program2.command("preflight").description("Unified diagnostic report: journal, drift, status, validation").option("--quick", "Skip drift detection for faster results").action(async (options) => {
+    try {
+      const cwd = process.cwd();
+      const graph = await loadGraph(cwd);
+      const yggRoot = await findYggRoot(cwd);
+      const journalEntries = await readJournal(yggRoot);
+      const driftedEntries = options.quick ? [] : (await detectDrift(graph)).entries.filter((e) => e.status !== "ok");
+      const nodeCount = graph.nodes.size;
+      const aspectCount = graph.aspects.length;
+      const flowCount = graph.flows.length;
+      let mappedPathCount = 0;
+      for (const node of graph.nodes.values()) {
+        mappedPathCount += normalizeMappingPaths(node.meta.mapping).length;
+      }
+      const validation = await validate(graph, "all");
+      const errors = validation.issues.filter((i) => i.severity === "error");
+      const warnings = validation.issues.filter((i) => i.severity === "warning");
+      const lines = [];
+      lines.push("=== Preflight Report ===");
+      lines.push("");
+      if (journalEntries.length === 0) {
+        lines.push("Journal:    clean");
+      } else {
+        lines.push(`Journal:    ${journalEntries.length} pending entries`);
+        for (const entry of journalEntries) {
+          const target = entry.target ? ` [${entry.target}]` : "";
+          lines.push(`            - ${entry.note}${target}`);
+        }
+      }
+      lines.push("");
+      if (options.quick) {
+        lines.push("Drift:      skipped (--quick)");
+      } else if (driftedEntries.length === 0) {
+        lines.push("Drift:      clean");
+      } else {
+        lines.push(`Drift:      ${driftedEntries.length} nodes need attention`);
+        for (const entry of driftedEntries) {
+          lines.push(`            - ${entry.nodePath}: ${entry.status}`);
+        }
+      }
+      lines.push("");
+      lines.push(
+        `Status:     ${nodeCount} nodes, ${aspectCount} aspects, ${flowCount} flows, ${mappedPathCount} mapped paths`
+      );
+      if (nodeCount === 0) {
+        lines.push("");
+        lines.push("            \u26A1 No nodes found. Enter BOOTSTRAP MODE:");
+        lines.push("            Create nodes under .yggdrasil/model/ for your active work area.");
+        lines.push("            See: yg help build-context");
+      }
+      lines.push("");
+      if (errors.length === 0 && warnings.length === 0) {
+        lines.push("Validation: clean");
+      } else {
+        const parts = [];
+        if (errors.length > 0) parts.push(`${errors.length} errors`);
+        if (warnings.length > 0) parts.push(`${warnings.length} warnings`);
+        lines.push(`Validation: ${parts.join(", ")}`);
+        for (const issue of [...errors, ...warnings]) {
+          const code = issue.code ? `[${issue.code}] ` : "";
+          const loc = issue.nodePath ? `${issue.nodePath} -> ` : "";
+          lines.push(`            - ${code}${loc}${issue.message}`);
+        }
+      }
+      lines.push("");
+      process.stdout.write(lines.join("\n"));
+      const hasIssues = journalEntries.length > 0 || !options.quick && driftedEntries.length > 0 || errors.length > 0;
+      process.exit(hasIssues ? 1 : 0);
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
+
 // src/bin.ts
+import { readFileSync } from "fs";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import { dirname, join } from "path";
+var __filename = fileURLToPath3(import.meta.url);
+var __dirname = dirname(__filename);
+var pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 var program = new Command();
-program.name("yg").description("Yggdrasil \u2014 architectural knowledge infrastructure for AI agents").version("0.1.0");
+program.name("yg").description("Yggdrasil \u2014 architectural knowledge infrastructure for AI agents").version(pkg.version);
 registerInitCommand(program);
 registerBuildCommand(program);
 registerValidateCommand(program);
@@ -3369,8 +3952,11 @@ registerTreeCommand(program);
 registerOwnerCommand(program);
 registerDepsCommand(program);
 registerImpactCommand(program);
+registerAspectsCommand(program);
+registerFlowsCommand(program);
 registerJournalAddCommand(program);
 registerJournalReadCommand(program);
 registerJournalArchiveCommand(program);
+registerPreflightCommand(program);
 program.parse();
 //# sourceMappingURL=bin.js.map