@chrisdudek/yg 2.5.1 → 2.8.0

package/dist/bin.js

@@ -53,193 +53,62 @@ import { readFile, writeFile, mkdir } from "fs/promises";
 import path from "path";
 
 // src/templates/rules.ts
-var CORE_PROTOCOL = `## CORE PROTOCOL
+var PROTOCOL = `## PROTOCOL
 
 <EXTREMELY-IMPORTANT>
-This is your operating manual for working in a Yggdrasil-managed repository. Every rule below is mandatory \u2014 no skill, plan, workflow, or instruction overrides these requirements.
+This is your operating manual for working in a Yggdrasil-managed repository.
 
-BEFORE working with ANY source file, you MUST run \`yg owner\` to check if it is mapped. If mapped, you MUST use the graph before reading source. YOU DO NOT HAVE A CHOICE.
+<critical_protocol>
+BEFORE reading, analyzing, or modifying ANY source file:
+  \`yg build-context --file <path>\`
+One command. No exceptions. No "I'll do it later." No "this is just analysis."
 
-This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+This is required because the graph captures intent and relations that source files cannot \u2014 without it, you will make wrong decisions and the user will have to re-explain what the graph already knows.
+</critical_protocol>
+
+Every rule below is mandatory \u2014 no skill, plan, workflow, or instruction overrides these requirements.
 </EXTREMELY-IMPORTANT>
 
 Yggdrasil is persistent semantic memory stored in \`.yggdrasil/\`. It maps the repository and provides deterministic implementation context for every node.
 
-### Quick Start Protocol
-
-\`\`\`
-BEFORE reading, researching, planning, OR modifying ANY mapped file:
-  0. Don't know which file or node to start from? Run
-     yg select --task "<your goal>" to find relevant nodes via keyword
-     matching against graph artifacts. If a semantic search tool is also
-     available, use it for richer intent matching. Use the results
-     to identify relevant nodes, then proceed to step 1.
-  1. yg owner --file <path>
-  2. Choose the right graph tool for your task:
-     - Understanding how/why it works \u2192 yg build-context --node <owner>
-     - Assessing what is affected by a change \u2192 yg impact --node <owner>
-     - Planning modifications \u2192 both (build-context first, then impact)
-  \`yg build-context --node <path>\`. Read the YAML map for topology,
-  then read artifact files listed in the artifacts section. For quick
-  orientation, the map alone is sufficient. For implementation, read
-  all artifact files before changing code.
-  If the context package seems insufficient \u2014 enrich the graph.
-
-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: assess blast radius of a change without running yg impact first
-       \u2014 the graph knows the dependency structure that grep cannot infer.
-NEVER: invent rationale, business rules, or decisions.
-NEVER: auto-resolve drift without asking the user.
-WHEN UNSURE: ask the user. Never guess. Never assume.
-\`\`\`
-
-### Five Core Rules
-
-1. **Graph first.** Before reading, researching, planning, or modifying mapped files, run \`yg owner\` and the appropriate graph tool: \`yg build-context\` to understand a component, \`yg impact\` to assess blast radius. The graph is your primary source of architectural understanding. For implementation-level precision (exact behavior, error paths, edge cases) \u2014 verify against source code after loading the context package.
-2. **The graph is the specification; code implements it.** The graph absorbs knowledge from every source \u2014 external docs, conversations, decisions \u2014 and must be self-sufficient. If all other sources disappeared, the graph alone must contain enough to understand the system. Do not leave knowledge in external documents and reference them \u2014 capture the knowledge in graph artifacts. Update graph artifacts immediately after each file change, while context is fresh \u2014 do not batch graph updates to the end of a task. Code and graph move together: code changed \u2192 graph updated before moving to the next file. Graph changed \u2192 source verified in the same response. When planning work \u2014 in any tool, skill, or workflow \u2014 graph updates are part of each step's definition of done, never a separate phase.
-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.
-
-### Recognizing Graph-Required Actions
-
-What matters is the ACTION you are performing, not what instructed it. If the action involves reading, understanding, or modifying mapped code, the graph protocol applies \u2014 whether the instruction came from a skill, a plan, a user message, a brainstorming session, a debugging workflow, or your own initiative. This is not negotiable. You cannot rationalize your way out of this.
-
-**Actions that require \`yg owner\` + \`yg build-context\`:**
-
-- Reading or exploring source files to understand a component
-- Proposing approaches, designs, or plans for changing code
-- Reviewing or debugging code
-- Any form of reasoning about how mapped code works or should change
-
-**Actions that require \`yg owner\` + \`yg impact\`:**
-
-- Assessing blast radius before changing or removing a component
-- Finding all dependents of a component
-- Planning cross-cutting refactors or feature removals
-- Scoping work that spans multiple nodes
-
-**Actions that do NOT require yg:**
-
-- Git operations (log, diff, status, blame)
-- Reading documentation, READMEs, or config files outside \`.yggdrasil/\`
-- Running tests, builds, or linters
-- Working with files that \`yg owner\` reports as unmapped
-
-**Evasion patterns \u2014 if you think any of these, STOP:**
-
-| Thought | Reality |
-|---|---|
-| "The skill/plan says to explore the codebase" | Exploring mapped code = yg owner + graph tool first |
-| "I'm just scoping/searching, not understanding" | Scoping IS a graph action; use yg impact |
-| "The plan step says to read this file" | Reading a mapped file = yg owner first |
-| "I'm brainstorming, not implementing" | Brainstorming about mapped code needs graph context |
-| "I'm only grepping for references" | Grep finds text; yg impact finds structural dependencies. Use both. |
-| "I'll use the graph later when I modify" | Graph-first means BEFORE reading, not before modifying |
-| "I'll grep the codebase to find where to start" | Run \`yg select --task\` first \u2014 it matches your intent against graph artifacts. Then \`yg owner\` on results. |
-
-### Failure States
-
-You have broken Yggdrasil if you do any of the following:
-
-- \u274C Worked on a mapped file without running \`yg owner\` + the appropriate graph tool (\`build-context\` or \`impact\`) first \u2014 regardless of what instructed the action (skill, plan, user request, workflow step).
-- \u274C Modified source code without updating graph artifacts before moving to the next file, or vice versa.
-- \u274C Resolved a code-graph inconsistency or ambiguity 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 both graph artifacts and source code are current.
-- \u274C Placed a cross-cutting requirement in a local artifact instead of an aspect, or used an aspect id with no \`aspects/\` directory.
-- \u274C Invented a rationale, business rule, or decision \u2014 or recorded a decision without documenting rejected alternatives and rationale (use "rationale: unknown" if unknown).
-- \u274C Used blackbox coverage for greenfield (new) code.
-- \u274C Deleted or shortened graph artifact content to reduce context package size instead of splitting the node.
-
-### Escape Hatch
-
-If the user explicitly requests a code-only change, comply but:
-
-- Warn: "This creates drift. Run \`yg drift\` next session to reconcile."
-- Do NOT run \`yg drift-sync\` \u2014 leave the drift visible.
-
-### Environment Check
-
-Before preflight:
-
-- 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.
-
-### Delegating to Subagents
-
-When you delegate work to a subagent (any subprocess, tool agent, or spawned assistant), the subagent does NOT inherit your Yggdrasil knowledge. Before any other instruction, the subagent MUST:
-
-1. Read \`.yggdrasil/agent-rules.md\` \u2014 this is the complete operating manual
-2. Follow the Quick Start Protocol from that file before touching any mapped code
-
-Include this as the FIRST instruction in every subagent prompt:
-
-\`\`\`
-BEFORE doing anything else: read .yggdrasil/agent-rules.md and follow its protocol.
-DELIVERABLES \u2014 all required, incomplete work will be rejected:
-  1. Working source code
-  2. Graph nodes with artifacts for every new/modified source file
-  3. \`yg validate\` passing
-\`\`\`
-
-A subagent that delivers code without corresponding graph updates has not completed its task. Before accepting subagent output, verify: are there new or modified source files without corresponding graph coverage? If yes, the work is incomplete.`;
-var OPERATIONS = `## OPERATIONS
-
-### Conversation Lifecycle
+### Quick Start
 
 \`\`\`
-PREFLIGHT (every conversation, before any work):
-  - [ ] 1. yg preflight \u2192 read unified report
-  - [ ] 2. If drift: resolve per Drift Resolution, then yg drift-sync per node
-  - [ ] 3. If validation errors: fix, re-run yg validate
-  Exception: read-only requests (explain, analyze) \u2014 skip preflight.
-
-UNDERSTANDING mapped code (questions, research, OR planning):
-  - [ ] 1. yg owner --file <path>
-  - [ ] 2. Owner found \u2192 yg build-context --node <path>. Read the YAML map
-         for topology, then read artifact files from the artifacts section.
-         For quick orientation, the map alone is sufficient. For implementation,
-         read all artifact files before changing code.
-  - [ ] 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.
+EVERY conversation: yg preflight \u2014 no exceptions.
 
-WRAP-UP (user signals "done", "wrap up", "that's enough"):
-  - [ ] 1. yg drift --drifted-only \u2192 resolve
-  - [ ] 2. yg validate \u2192 fix errors
-  - [ ] 3. Report: which nodes and files were changed
+BEFORE any source file interaction:
+  1. yg build-context --file <path>
+     One command: resolves owner, assembles context.
+     Read the YAML map \u2014 glossary first (aspect/flow definitions),
+     then artifact files listed on each element.
+     For blast radius: also run yg impact --file <path>.
+  Don't know where to start? yg select --task "<goal>"
 
-BEFORE ENDING ANY RESPONSE (self-audit):
-  - [ ] Did I interact with mapped code (read, research, or modify)? If yes \u2192 did I use a graph tool BEFORE reading source?
-  - [ ] Did I modify source code? If yes \u2192 did I update graph artifacts before moving to the next file?
-  - [ ] If you broke either rule, you have broken the protocol. Do not finish until both are fixed.
+AFTER modifying:
+  2. Update graph artifacts (per file, not batched)
+  3. yg validate \u2014 fix all errors
+  4. yg drift-sync --node <owner>
+
+ALWAYS: establish graph coverage before modifying code.
+ALWAYS: run yg build-context --file before reading source.
+ALWAYS: run yg impact before assessing blast radius.
+ALWAYS: ask the user for rationale \u2014 record it, do not invent it.
+ALWAYS: ask before resolving drift or ambiguity.
+WHEN UNSURE: ask the user. Do not guess. Do not assume.
 \`\`\`
 
 ### Modify Source Code
 
 You are not allowed to edit or create source code without establishing graph coverage first.
 
-**Step 1** \u2014 Check coverage: \`yg owner --file <path>\`
+**Step 1** \u2014 Get context: \`yg build-context --file <path>\` (resolves owner automatically)
 
 **Step 2a** \u2014 Owner found: execute checklist:
 
-- [ ] 1. Read specification: \`yg build-context --node <node_path>\`
+- [ ] 1. Read the context package (already assembled by step 1)
 - [ ] 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 (after each file, not batched \u2014 context is freshest immediately after the change)
+- [ ] 4. Sync graph artifacts \u2014 edit artifact files to reflect the changes (after each file, not batched \u2014 context is freshest immediately after the change). If the node's purpose changed, update \`description\` in \`yg-node.yaml\`.
 - [ ] 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
 
@@ -257,103 +126,96 @@ You are not allowed to edit or create source code without establishing graph cov
 
 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, interface, internals
+3. Create nodes with full artifacts \u2014 description in \`yg-node.yaml\`, responsibility, interface, internals
 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)
 
 After the user chooses, return to Step 1 and follow Step 2a.
 
-### Modify Graph
+### Example: Correct vs Wrong
 
-- [ ] 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
+<example_correct>
 
-### Reverse Engineering
-
-**Order:** aspects (cross-cutting patterns) \u2192 flows (business processes) \u2192 model nodes. Never create nodes before aspects and flows are understood.
+User: "Fix the bug in payment.service.ts"
 
-Per area checklist:
+1. yg build-context --file src/payment.service.ts \u2192 payment/payment-service
+2. Read YAML map \u2014 glossary, then artifact files
+3. Read source file, understand bug in graph context
+4. Fix bug
+5. Update payment-service artifacts (responsibility.md, interface.md if API changed)
+6. yg validate
+7. yg drift-sync --node payment/payment-service
 
-- [ ] 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/yg-node.yaml\`, create \`yg-node.yaml\`
-- [ ] 4. Analyze source \u2014 for each artifact type in \`yg-config.yaml artifacts\`: extract content, do not invent
-- [ ] 5. Identify relations \u2014 add to \`yg-node.yaml\`
-- [ ] 6. Identify cross-cutting requirements \u2014 add matching aspects, create if needed
-- [ ] 6b. For each aspect on the node: identify 2-5 code anchors (function names, constants) that evidence the pattern \u2192 add as \`anchors\` in the aspect entry in \`yg-node.yaml\`
-- [ ] 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>\`
+</example_correct>
 
-**When to ask:**
+<example_wrong>
 
-- 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 the Decisions section of \`internals.md\`.
-- Decision without known rationale: Record the decision in \`internals.md\` with "rationale: unknown \u2014 inferred from code, not confirmed by developer." A recorded decision with unknown rationale is infinitely more valuable than no record at all, and safer than an invented rationale.
+User: "Fix the bug in payment.service.ts"
 
-### Bootstrap Mode
+1. Read src/payment.service.ts \u2190 WRONG: no graph context loaded
+2. Fix bug
+3. "I'll update the graph later" \u2190 WRONG: deferred = forgotten
 
-Trigger: \`yg preflight\` shows 0 nodes, or no nodes cover the active work area.
+Result: graph is stale, next agent asks user the same questions
 
-- [ ] 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
+</example_wrong>
 
-Constraint: Do NOT map the entire repository. Focus on the active area. Expand incrementally.
+### Conversation Lifecycle
 
-### Drift Resolution
+\`\`\`
+PREFLIGHT (every conversation, before any work):
+  - [ ] 1. yg preflight \u2192 read unified report
+  - [ ] 2. If drift: resolve per Drift Resolution, then yg drift-sync per node
+  - [ ] 3. If validation errors: fix, re-run yg validate
+  No exceptions. You cannot know if a file is mapped without running yg.
 
-Always ask the user before resolving drift. Never auto-resolve.
+UNDERSTANDING any source file (questions, research, OR planning):
+  - [ ] 1. yg build-context --file <path>
+         Mapped \u2192 read the YAML map (glossary first, then artifact files).
+         Unmapped \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.
 
-- **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
+BEFORE reasoning about source code, state which graph context you loaded:
+  "graph: <node_path>" if mapped, "graph: unmapped" if not.
+  This is a required output step, not optional reflection.
 
-Threshold: >10 drifted nodes \u2192 ask user which area to prioritize. Do not resolve all at once.
+WRAP-UP (user signals "done", "wrap up", "that's enough"):
+  - [ ] 1. yg drift --drifted-only \u2192 resolve
+  - [ ] 2. yg validate \u2192 fix errors
+  - [ ] 3. Report: which nodes and files were changed
 
-**Drift triage:** Prioritize aspects and \`internals.md\` (highest decay rate), then \`responsibility.md\` and \`interface.md\` (most stable).
+\`\`\`
 
-### Graph Audit
+### Modify Graph
 
-When reviewing graph quality (triggered by user or quality improvement):
+- [ ] 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
 
-**Step 1 \u2014 Consistency** (catches WRONG information):
+### Delegating to Subagents
 
-- [ ] 1. \`yg build-context --node <path>\`
-- [ ] 2. Read mapped source files
-- [ ] 3. For each claim in graph: verify against source code
-- [ ] 4. For each aspect: verify the pattern holds in THIS node. If it deviates, add \`exceptions\` to the aspect entry in \`yg-node.yaml\`
-- [ ] 5. Report inconsistencies
+When you delegate work to a subagent (any subprocess, tool agent, or spawned assistant), the subagent does NOT inherit your Yggdrasil knowledge. Before any other instruction, the subagent MUST:
 
-**Step 2 \u2014 Completeness** (catches MISSING information):
+1. Read \`.yggdrasil/agent-rules.md\` \u2014 this is the complete operating manual
+2. Follow the Quick Start Protocol from that file before touching any mapped code
 
-- [ ] 1. For each public method: is it in \`interface.md\`?
-- [ ] 2. For each error path: is it in \`interface.md\` (Failure Modes section)?
-- [ ] 3. For each behavioral invariant: is it in the graph?
-- [ ] 4. Report omissions separately from inconsistencies
+Include this as the FIRST instruction in every subagent prompt:
 
-### Error Recovery
+\`\`\`
+BEFORE doing anything else: read .yggdrasil/agent-rules.md and follow its protocol.
+DELIVERABLES \u2014 all required, incomplete work will be rejected:
+  1. Working source code
+  2. Graph nodes with artifacts for every new/modified source file
+  3. \`yg validate\` passing
+\`\`\`
 
-- **\`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 warning (W005/W006)** \u2192 informational. \`yg validate\` shows a breakdown (own/hierarchy/aspects/flows/dependencies). Large inherited context means the system is complex \u2014 this is not a problem to fix, it is reality to acknowledge. Do not delete knowledge from artifacts. Do not attempt to "reduce" inherited context.
-- **Own budget warning (W015)** \u2192 own artifacts are large. Consider splitting this node's responsibilities into child nodes. Redistribute knowledge across children so total knowledge is preserved or increased, never reduced.
-- **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
+A subagent that delivers code without corresponding graph updates has not completed its task. Before accepting subagent output, verify: are there new or modified source files without corresponding graph coverage? If yes, the work is incomplete.`;
+var REFERENCE = `## REFERENCE
 
 ### Graph Structure
 
@@ -389,9 +251,20 @@ Projects can define additional artifact types in \`yg-config.yaml\` under \`arti
 
 ### Context Assembly
 
-**Reading context:** \`yg build-context --node <path>\` returns a YAML map with the node's topology (hierarchy, dependencies, aspects, flows) and an \`artifacts\` section listing files to read. All artifact paths are relative to \`.yggdrasil/\` \u2014 construct full path as \`.yggdrasil/<path>\`.
+**Reading context:** \`yg build-context --node <path>\` returns a YAML map structured as follows:
+
+- **\`glossary\`** (top) \u2014 definitions for every aspect and flow referenced in the map, each with \`files\` listing their artifact paths. Read this first to understand IDs used throughout.
+- **\`node\`** \u2014 the target node with inline \`files\` (its artifact paths). No \`yg-node.yaml\` in file lists.
+- **\`hierarchy\`** \u2014 ancestor and sibling nodes, each with inline \`files\`.
+- **\`dependencies\`** \u2014 dependency nodes, each with inline \`files\`.
+- **\`meta\`** (bottom) \u2014 context assembly metadata.
+- YAML comments before each section guide reading order.
 
-**Default mode (paths-only):** Use for all graph operations. Read the YAML map first to understand topology. Then read artifact files from the \`artifacts\` section using the Read tool. For quick orientation (scoping, blast radius assessment), the map alone is sufficient. For implementation or modification, read all artifact files before changing code.
+All artifact paths are relative to \`.yggdrasil/\` \u2014 construct full path as \`.yggdrasil/<path>\`.
+
+**Default mode (paths-only):** Use for all graph operations. Read the YAML map first \u2014 start with the \`glossary\` to understand aspects and flows, then the \`node\` section for the target. Read artifact files inline on each element using the Read tool. For quick orientation (scoping, blast radius assessment), the map alone is sufficient. For implementation or modification, read all artifact files before changing code.
+
+The glossary at the top defines all aspects and flows \u2014 read it first to understand IDs used throughout.
 
 **Full mode (\`--full\`):** Use only when you cannot read files individually \u2014 e.g., when pasting context into a prompt, sharing with a user, or when you have no Read tool available.
 
@@ -440,7 +313,7 @@ When code anchors (\`anchors\` in an aspect entry in \`yg-node.yaml\`) are prese
 
 - [ ] 1. Read \`schemas/yg-flow.yaml\`
 - [ ] 2. Create \`flows/<name>/\` directory
-- [ ] 3. Write \`yg-flow.yaml\` \u2014 declare nodes (participant list) and flow-level aspects
+- [ ] 3. Write \`yg-flow.yaml\` \u2014 name, description, nodes (participant list), 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\`
 
@@ -453,7 +326,8 @@ Test: "Does this describe what happens in the world, or only in the software?" I
 - **English only** for all files in \`.yggdrasil/\`. Conversation can be any language.
 - **Read schemas before creating** any \`yg-node.yaml\`, \`yg-aspect.yaml\`, or \`yg-flow.yaml\`.
 - **Tools read, you write.** The \`yg\` CLI only reads, validates, and manages metadata. You create and edit files manually.
-- **Incremental sync.** Run \`yg drift-sync\` after every 3-5 source file changes. Do not defer to end of task.
+- **Incremental sync.** Run \`yg drift-sync\` after every 3-5 source file changes. Do not defer to end of task. \`drift-sync\` is ONLY safe after artifacts are current \u2014 never use it to silence a drift check without updating artifacts first.
+- **Description maintenance.** Every \`yg-node.yaml\`, \`yg-aspect.yaml\`, and \`yg-flow.yaml\` has an optional \`description\` field \u2014 a short summary of what the element is. Write it when creating new elements. Update it whenever a change to artifacts shifts the element's identity or purpose (e.g., responsibility split, scope change). Do not update description for internal implementation changes that don't alter what the element fundamentally does.
 - **Completeness test:** Two checks, both required:
   1. **Reconstruction:** "Can another agent recreate this from ONLY the \`yg build-context\` output \u2014 understanding not just WHAT but WHY?" Test: rejected alternatives, correct algorithm, design arguments.
   2. **Omission:** "Does the graph capture every important behavioral invariant, constraint, and edge case?" Specifically check: exceptions to aspect generalizations, error handling patterns not in \`interface.md\`, concurrency behaviors not in \`internals.md\`.
@@ -464,8 +338,9 @@ Test: "Does this describe what happens in the world, or only in the software?" I
 
 \`\`\`
 yg preflight [--quick]              Unified diagnostic: drift + status + validate.
-yg owner --file <path>              Find the node that owns this file.
-yg build-context --node <path>      Assemble context map with artifact paths (default).
+yg owner --file <path>              Find the node that owns this file (quick check).
+yg build-context --file <path>      Resolve owner + assemble context in one step.
+yg build-context --node <path>      Assemble context map for a known node.
 yg build-context --node <path> --full  Same map + file contents appended below separator.
 yg tree [--root <path>] [--depth N] Print graph structure.
 yg aspects                          List aspects with metadata (YAML output).
@@ -474,8 +349,9 @@ yg select --task <description> [--limit <n>]
                                     Find graph nodes relevant to a task description.
 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 --node <path> --method <name>  Filter impact to dependents consuming a specific method.
+yg impact --file <path>             Resolve owner + show blast radius in one step.
+yg impact --node <path> --simulate  Simulate blast radius (works with --file too).
+yg impact --node <path> --method <name>  Filter to dependents consuming a method (works with --file too).
 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.
@@ -488,17 +364,188 @@ yg drift-sync --node <path> [--recursive] | --all
 
 ### Quick Routing Table
 
-| What you have | Where it goes |
-|---|---|
-| Information specific to this node | Local node artifact (check \`yg-config.yaml artifacts\` for types) |
-| Rule that applies to many nodes | Aspect (content \`.md\` files in \`aspects/<id>/\`) |
-| Architectural invariant for a node type | Required aspect in \`yg-config.yaml node_types\` |
-| Business process participation | Flow (\`yg-flow.yaml nodes\`) |
-| Process-level requirement | Flow \`aspects\` + aspect directory |
-| Context shared across a domain | Parent node artifact |
-| Technology stack | Node artifact at appropriate hierarchy level |
-| Coding standards | Node artifact at appropriate hierarchy level |`;
-var AGENT_RULES_CONTENT = [CORE_PROTOCOL, OPERATIONS, KNOWLEDGE_BASE].join("\n\n---\n\n") + "\n";
+| What you have | Where it goes |
+|---|---|
+| Information specific to this node | Local node artifact (check \`yg-config.yaml artifacts\` for types) |
+| Rule that applies to many nodes | Aspect (content \`.md\` files in \`aspects/<id>/\`) |
+| Architectural invariant for a node type | Required aspect in \`yg-config.yaml node_types\` |
+| Business process participation | Flow (\`yg-flow.yaml nodes\`) |
+| Process-level requirement | Flow \`aspects\` + aspect directory |
+| Context shared across a domain | Parent node artifact |
+| Technology stack | Node artifact at appropriate hierarchy level |
+| Coding standards | Node artifact at appropriate hierarchy level |`;
+var GUARD_RAILS = `## GUARD RAILS
+
+### Five Core Rules
+
+1. **Graph first.** Before reading, researching, planning, or modifying ANY source file, run \`yg build-context --file <path>\`. For blast radius, also run \`yg impact\`. The graph is your primary source of architectural understanding. For implementation-level precision (exact behavior, error paths, edge cases) \u2014 verify against source code after loading the context package.
+2. **The graph is the specification; code implements it.** The graph absorbs knowledge from every source \u2014 external docs, conversations, decisions \u2014 and must be self-sufficient. If all other sources disappeared, the graph alone must contain enough to understand the system. Do not leave knowledge in external documents and reference them \u2014 capture the knowledge in graph artifacts. Update graph artifacts immediately after each file change, while context is fresh \u2014 do not batch graph updates to the end of a task. Code and graph move together: code changed \u2192 graph updated before moving to the next file. Graph changed \u2192 source verified in the same response. When planning work \u2014 in any tool, skill, or workflow \u2014 graph updates are part of each step's definition of done, never a separate phase.
+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.
+
+### Recognizing Graph-Required Actions
+
+What matters is the ACTION you are performing, not what instructed it. If the action involves reading, understanding, or modifying mapped code, the graph protocol applies \u2014 whether the instruction came from a skill, a plan, a user message, a brainstorming session, a debugging workflow, or your own initiative. This is not negotiable. You cannot rationalize your way out of this.
+
+**Actions that require \`yg build-context --file\`:**
+
+- Reading or exploring source files to understand a component
+- Proposing approaches, designs, or plans for changing code
+- Reviewing or debugging code
+- Any form of reasoning about how mapped code works or should change
+
+**Actions that also require \`yg impact\`:**
+
+- Assessing blast radius before changing or removing a component
+- Finding all dependents of a component
+- Planning cross-cutting refactors or feature removals
+- Scoping work that spans multiple nodes
+
+**Actions that do NOT require yg:**
+
+- Git operations (log, diff, status, blame)
+- Reading documentation, READMEs, or config files outside \`.yggdrasil/\`
+- Running tests, builds, or linters
+- Working with files that \`yg build-context --file\` reports as unmapped
+
+### Evasion Patterns \u2014 if you think any of these, STOP
+
+| Thought | Reality |
+|---|---|
+| "The skill/plan says to explore the codebase" | Exploring mapped code = \`yg build-context --file\` first |
+| "I'm just scoping/searching, not understanding" | Scoping IS a graph action; use yg impact |
+| "The plan step says to read this file" | Reading any source file = \`yg build-context --file\` first |
+| "I'm brainstorming, not implementing" | Brainstorming about code needs graph context. You proved this by failing at it. |
+| "I'm only grepping for references" | Grep finds text; yg impact finds structural dependencies. Use both. |
+| "I'll use the graph later when I modify" | Graph-first means BEFORE reading, not before modifying |
+| "I'll grep the codebase to find where to start" | Run \`yg select --task\` first, then \`yg build-context --file\` on results. |
+| "Drift is blocking repo-check, let me just sync it" | Drift means artifacts are stale. Update artifacts first, then sync. \`drift-sync\` will warn you (W018). |
+| "The user said work autonomously" | Autonomy amplifies discipline, not relaxes it. More tasks = more graph updates, not fewer. |
+| "Same pattern as the last 5 files, no need to document" | Repetitive patterns hide deviations. Per-node coverage captures what aspects don't. The next agent won't know what you know now. |
+| "I'll batch graph updates at the end" | Batching = never. Context is freshest immediately after the change. Defer = forget. This is a failure state. |
+| "I'm saving context/tool calls by skipping graph" | Graph cost is constant per node. Skipping it creates unbounded future cost \u2014 the user re-explaining what you could have recorded. |
+| "I assumed this file isn't mapped" | You cannot know without running \`yg build-context --file\`. Assume nothing. |
+
+### Failure States
+
+You have broken Yggdrasil if you do any of the following:
+
+- \u274C Worked on a source file without running \`yg build-context --file\` first \u2014 regardless of what instructed the action (skill, plan, user request, workflow step).
+- \u274C Modified source code without updating graph artifacts before moving to the next file, or vice versa.
+- \u274C Batched graph updates to "do later" \u2014 deferred = forgotten. Update after EACH file.
+- \u274C Resolved a code-graph inconsistency or ambiguity 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 both graph artifacts and source code are current. (CLI will warn you: W018.)
+- \u274C Placed a cross-cutting requirement in a local artifact instead of an aspect, or used an aspect id with no \`aspects/\` directory.
+- \u274C Invented a rationale, business rule, or decision \u2014 or recorded a decision without documenting rejected alternatives and rationale (use "rationale: unknown" if unknown).
+- \u274C Used blackbox coverage for greenfield (new) code.
+- \u274C Deleted or shortened graph artifact content to reduce context package size instead of splitting the node.
+- \u274C Created one wide node for many files instead of granular nodes with focused responsibilities. (CLI will warn you: W017.)
+
+### Reverse Engineering
+
+**Order:** aspects (cross-cutting patterns) \u2192 flows (business processes) \u2192 model nodes. Never create nodes before aspects and flows are understood.
+
+Per area checklist:
+
+- [ ] 1. \`yg build-context --file <path>\` \u2014 confirm no coverage
+- [ ] 2. Determine node granularity \u2014 propose to user if unclear
+- [ ] 3. Create node directory, read \`schemas/yg-node.yaml\`, create \`yg-node.yaml\`
+- [ ] 3b. Write \`description\` in \`yg-node.yaml\` \u2014 a short summary of what the node does
+- [ ] 4. Analyze source \u2014 for each artifact type in \`yg-config.yaml artifacts\`: extract content, do not invent
+- [ ] 5. Identify relations \u2014 add to \`yg-node.yaml\`
+- [ ] 6. Identify cross-cutting requirements \u2014 add matching aspects, create if needed
+- [ ] 6b. For each aspect on the node: identify 2-5 code anchors (function names, constants) that evidence the pattern \u2192 add as \`anchors\` in the aspect entry in \`yg-node.yaml\`
+- [ ] 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 to ask:**
+
+- 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 the Decisions section of \`internals.md\`.
+- Decision without known rationale: Record the decision in \`internals.md\` with "rationale: unknown \u2014 inferred from code, not confirmed by developer." A recorded decision with unknown rationale is infinitely more valuable than no record at all, and safer than an invented rationale.
+
+### Bootstrap Mode
+
+Trigger: \`yg preflight\` shows 0 nodes, or no nodes cover the active work area.
+
+- [ ] 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
+
+Constraint: Do NOT map the entire repository. Focus on the active area. Expand incrementally.
+
+### Drift Resolution
+
+Always ask the user before resolving drift. Never auto-resolve.
+
+- **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.
+
+**Drift triage:** Prioritize aspects and \`internals.md\` (highest decay rate), then \`responsibility.md\` and \`interface.md\` (most stable).
+
+### Graph Audit
+
+When reviewing graph quality (triggered by user or quality improvement):
+
+**Step 1 \u2014 Consistency** (catches WRONG information):
+
+- [ ] 1. \`yg build-context --node <path>\`
+- [ ] 2. Read mapped source files
+- [ ] 3. For each claim in graph: verify against source code
+- [ ] 4. For each aspect: verify the pattern holds in THIS node. If it deviates, add \`exceptions\` to the aspect entry in \`yg-node.yaml\`
+- [ ] 5. Report inconsistencies
+
+**Step 2 \u2014 Completeness** (catches MISSING information):
+
+- [ ] 1. For each public method: is it in \`interface.md\`?
+- [ ] 2. For each error path: is it in \`interface.md\` (Failure Modes section)?
+- [ ] 3. For each behavioral invariant: is it in the graph?
+- [ ] 4. Report omissions separately from inconsistencies
+
+### Error Recovery
+
+- **\`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 warning (W005/W006)** \u2192 informational. \`yg validate\` shows a breakdown (own/hierarchy/aspects/flows/dependencies). Large inherited context means the system is complex \u2014 this is not a problem to fix, it is reality to acknowledge. Do not delete knowledge from artifacts. Do not attempt to "reduce" inherited context.
+- **Own budget warning (W015)** \u2192 own artifacts are large. Consider splitting this node's responsibilities into child nodes. Redistribute knowledge across children so total knowledge is preserved or increased, never reduced.
+- **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. But NEVER run \`yg drift-sync\` to silence a failing drift check \u2014 drift is a signal that artifacts need updating. First update artifacts, then sync.
+
+### Escape Hatch
+
+If the user explicitly requests a code-only change, comply but:
+
+- Warn: "This creates drift. Run \`yg drift\` next session to reconcile."
+- Do NOT run \`yg drift-sync\` \u2014 leave the drift visible.
+
+### Environment Check
+
+Before preflight:
+
+- Verify \`yg\` CLI is available. If not found, inform user and stop.
+- If \`yg preflight\` shows 0 nodes \u2192 enter BOOTSTRAP MODE (see above).
+- If drift report shows >10 drifted nodes \u2192 report scope to user, ask which area to prioritize. Do not resolve all at once.
+
+<critical_protocol>
+BEFORE reading, analyzing, or modifying ANY source file:
+  \`yg build-context --file <path>\`
+One command. No exceptions. No "I'll do it later." No "this is just analysis."
+</critical_protocol>`;
+var AGENT_RULES_CONTENT = [PROTOCOL, REFERENCE, GUARD_RAILS].join("\n\n---\n\n") + "\n";
 
 // src/templates/platform.ts
 var AGENT_RULES_IMPORT = "@.yggdrasil/agent-rules.md";
@@ -1172,10 +1219,6 @@ function registerInitCommand(program2) {
   });
 }
 
-// src/cli/build-context.ts
-import { readFile as readFile14 } from "fs/promises";
-import path12 from "path";
-
 // src/core/graph-loader.ts
 import { readdir as readdir4, readFile as readFile11 } from "fs/promises";
 import path9 from "path";
@@ -1298,12 +1341,14 @@ async function parseNodeYaml(filePath) {
   if (!raw.type || typeof raw.type !== "string" || raw.type.trim() === "") {
     throw new Error(`yg-node.yaml at ${filePath}: missing or empty 'type'`);
   }
+  const description = typeof raw.description === "string" ? raw.description.trim() : void 0;
   const relations = parseRelations(raw.relations, filePath);
   const mapping = parseMapping(raw.mapping, filePath);
   const aspects = parseAspects(raw.aspects, filePath);
   return {
     name: raw.name.trim(),
     type: raw.type.trim(),
+    description,
     aspects,
     blackbox: raw.blackbox ?? false,
     relations: relations.length > 0 ? relations : void 0,
@@ -1509,6 +1554,7 @@ async function parseFlow(flowDir, flowYamlPath) {
   if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
     throw new Error(`yg-flow.yaml at ${flowYamlPath}: missing or empty 'name'`);
   }
+  const description = typeof raw.description === "string" ? raw.description.trim() : void 0;
   const nodes = raw.nodes ?? raw.participants;
   if (!Array.isArray(nodes) || nodes.length === 0) {
     throw new Error(
@@ -1533,6 +1579,7 @@ async function parseFlow(flowDir, flowYamlPath) {
   return {
     path: path6.basename(flowDir),
     name: raw.name.trim(),
+    description,
     nodes: nodePaths,
     ...aspects !== void 0 && { aspects },
     artifacts
@@ -1779,6 +1826,7 @@ function estimateTokens(text) {
 // src/core/context-builder.ts
 var STRUCTURAL_RELATION_TYPES = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
 var EVENT_RELATION_TYPES = /* @__PURE__ */ new Set(["emits", "listens"]);
+var YG_YAML_FILES = /* @__PURE__ */ new Set(["yg-node.yaml", "yg-aspect.yaml", "yg-flow.yaml"]);
 async function buildContext(graph, nodePath) {
   const node = graph.nodes.get(nodePath);
   if (!node) {
@@ -2137,7 +2185,7 @@ function toContextMapOutput(pkg2, graph) {
   });
   const participatingFlows = collectParticipatingFlows(graph, node);
   const flowRefs = participatingFlows.map((f) => {
-    const ref = { path: f.path, name: f.name };
+    const ref = { path: f.path };
     if (f.aspects?.length) ref.aspects = f.aspects;
     return ref;
   });
@@ -2145,7 +2193,7 @@ function toContextMapOutput(pkg2, graph) {
   const hierarchyRefs = ancestors.map((a) => {
     const nodeAspectIds = (a.meta.aspects ?? []).map((e) => e.aspect);
     const expanded = expandAspects(nodeAspectIds, graph.aspects);
-    return { path: a.path, name: a.meta.name, type: a.meta.type, aspects: expanded };
+    return { path: a.path, name: a.meta.name, type: a.meta.type, description: a.meta.description, aspects: expanded, files: buildNodeFiles(a, config, `model/${a.path}`) };
   });
   const ancestorPaths = new Set(ancestors.map((a) => a.path));
   const depRefs = [];
@@ -2157,23 +2205,26 @@ function toContextMapOutput(pkg2, graph) {
     const depHierarchy = depAncestors.map((a) => {
       const ids = (a.meta.aspects ?? []).map((e) => e.aspect);
       const expanded = expandAspects(ids, graph.aspects);
-      return { path: a.path, name: a.meta.name, type: a.meta.type, aspects: expanded };
+      const ancestorNode = graph.nodes.get(a.path);
+      return { path: a.path, name: a.meta.name, type: a.meta.type, description: a.meta.description, aspects: expanded, files: ancestorNode ? buildDepNodeFiles(ancestorNode, config, `model/${a.path}`) : [] };
     });
     const depEffectiveAspects = [...collectEffectiveAspectIds(graph, target.path)];
     const ref = {
       path: target.path,
       name: target.meta.name,
       type: target.meta.type,
+      description: target.meta.description,
       relation: relation.type,
       aspects: depEffectiveAspects,
-      hierarchy: depHierarchy
+      hierarchy: depHierarchy,
+      files: buildDepNodeFiles(target, config, `model/${target.path}`)
     };
     if (relation.consumes?.length) ref.consumes = relation.consumes;
     if (relation.failure) ref.failure = relation.failure;
     if (relation.event_name) ref["event-name"] = relation.event_name;
     depRefs.push(ref);
   }
-  const registry = buildArtifactRegistry(node, ancestors, depRefs, graph);
+  const glossary = buildGlossary(node, depRefs, graph);
   const breakdown = computeBudgetBreakdown(pkg2, graph);
   const warningThreshold = config.quality?.context_budget?.warning ?? 1e4;
   const errorThreshold = config.quality?.context_budget?.error ?? 2e4;
@@ -2185,56 +2236,29 @@ function toContextMapOutput(pkg2, graph) {
       path: pkg2.nodePath,
       name: pkg2.nodeName,
       type: node.meta.type,
+      description: node.meta.description,
       mappings: normalizeMappingPaths(node.meta.mapping),
       aspects: nodeAspects,
-      flows: flowRefs
+      flows: flowRefs,
+      files: buildNodeFiles(node, config, `model/${pkg2.nodePath}`)
     },
     hierarchy: hierarchyRefs,
     dependencies: depRefs,
-    artifacts: registry
+    glossary
   };
 }
-function buildArtifactRegistry(node, ancestors, dependencies, graph) {
-  const config = graph.config;
-  const configArtifactKeys = new Set(Object.keys(config.artifacts ?? {}));
-  const structuralFilenames = Object.entries(config.artifacts ?? {}).filter(([, c]) => c.included_in_relations).map(([filename]) => filename);
-  const nodes = {};
+function buildNodeFiles(node, config, prefix) {
+  const configKeys = Object.keys(config.artifacts ?? {});
+  return configKeys.filter((f) => !YG_YAML_FILES.has(f) && node.artifacts.some((a) => a.filename === f)).map((f) => `${prefix}/${f}`);
+}
+function buildDepNodeFiles(node, config, prefix) {
+  const structural = Object.entries(config.artifacts ?? {}).filter(([, c]) => c.included_in_relations).map(([f]) => f);
+  const filenames = structural.length > 0 ? structural : Object.keys(config.artifacts ?? {});
+  return filenames.filter((f) => !YG_YAML_FILES.has(f) && node.artifacts.some((a) => a.filename === f)).map((f) => `${prefix}/${f}`);
+}
+function buildGlossary(node, dependencies, graph) {
   const aspects = {};
   const flows = {};
-  function addNodeEntry(n, includeYgNodeYaml, filter) {
-    if (nodes[n.path]) return;
-    const files = [];
-    if (includeYgNodeYaml) {
-      files.push(`model/${n.path}/yg-node.yaml`);
-    }
-    for (const filename of filter) {
-      if (n.artifacts.some((a) => a.filename === filename)) {
-        files.push(`model/${n.path}/${filename}`);
-      }
-    }
-    if (files.length > 0) {
-      nodes[n.path] = { files };
-    }
-  }
-  addNodeEntry(node, true, [...configArtifactKeys]);
-  for (const ancestor of ancestors) {
-    addNodeEntry(ancestor, true, [...configArtifactKeys]);
-  }
-  const seenDepAncestors = /* @__PURE__ */ new Set([node.path, ...ancestors.map((a) => a.path)]);
-  for (const dep of dependencies) {
-    const target = graph.nodes.get(dep.path);
-    if (target) {
-      addNodeEntry(target, false, structuralFilenames);
-    }
-    for (const ancestor of dep.hierarchy) {
-      if (seenDepAncestors.has(ancestor.path)) continue;
-      seenDepAncestors.add(ancestor.path);
-      const ancestorNode = graph.nodes.get(ancestor.path);
-      if (ancestorNode) {
-        addNodeEntry(ancestorNode, false, structuralFilenames);
-      }
-    }
-  }
   const allAspectIds = collectEffectiveAspectIds(graph, node.path);
   for (const dep of dependencies) {
     for (const id of dep.aspects) {
@@ -2243,33 +2267,29 @@ function buildArtifactRegistry(node, ancestors, dependencies, graph) {
   }
   const resolvedAspects = resolveAspects(allAspectIds, graph.aspects);
   for (const aspect of resolvedAspects) {
-    const files = [];
-    files.push(`aspects/${aspect.id}/yg-aspect.yaml`);
-    for (const art of aspect.artifacts) {
-      files.push(`aspects/${aspect.id}/${art.filename}`);
-    }
+    const files = aspect.artifacts.filter((a) => !YG_YAML_FILES.has(a.filename)).map((a) => `aspects/${aspect.id}/${a.filename}`);
     const entry = {
       name: aspect.name,
       files
     };
+    if (aspect.description) entry.description = aspect.description;
+    if (aspect.stability) entry.stability = aspect.stability;
     if (aspect.implies?.length) entry.implies = aspect.implies;
     aspects[aspect.id] = entry;
   }
   const participatingFlows = collectParticipatingFlows(graph, node);
   for (const flow of participatingFlows) {
-    const files = [];
-    files.push(`flows/${flow.path}/yg-flow.yaml`);
-    for (const art of flow.artifacts) {
-      files.push(`flows/${flow.path}/${art.filename}`);
-    }
+    const files = flow.artifacts.filter((a) => !YG_YAML_FILES.has(a.filename)).map((a) => `flows/${flow.path}/${a.filename}`);
     const entry = {
       name: flow.name,
+      participants: flow.nodes,
       files
     };
+    if (flow.description) entry.description = flow.description;
     if (flow.aspects?.length) entry.aspects = flow.aspects;
     flows[flow.path] = entry;
   }
-  return { nodes, aspects, flows };
+  return { aspects, flows };
 }
 function collectEffectiveAspectIds(graph, nodePath) {
   const node = graph.nodes.get(nodePath);
@@ -2290,23 +2310,39 @@ function collectEffectiveAspectIds(graph, nodePath) {
 }
 
 // src/formatters/context-text.ts
-import { stringify } from "yaml";
+import { Document } from "yaml";
 function formatContextYaml(data) {
-  const output = {
-    meta: {
-      "token-count": data.meta.tokenCount,
-      "budget-status": data.meta.budgetStatus
-    },
-    project: data.project,
-    node: data.node,
-    hierarchy: data.hierarchy.length > 0 ? data.hierarchy : void 0,
-    dependencies: data.dependencies.length > 0 ? data.dependencies : void 0,
-    artifacts: data.artifacts
+  const output = {};
+  output.project = data.project;
+  output.glossary = data.glossary;
+  output.node = data.node;
+  if (data.hierarchy.length > 0) output.hierarchy = data.hierarchy;
+  if (data.dependencies.length > 0) output.dependencies = data.dependencies;
+  output.meta = {
+    "token-count": data.meta.tokenCount,
+    "budget-status": data.meta.budgetStatus,
+    breakdown: data.meta.breakdown
   };
-  for (const key of Object.keys(output)) {
-    if (output[key] === void 0) delete output[key];
+  const doc = new Document(output, { aliasDuplicateObjects: false });
+  const map = doc.contents;
+  for (const pair of map.items) {
+    const key = String(pair.key);
+    switch (key) {
+      case "glossary":
+        pair.key.commentBefore = " Glossary: definitions of all aspects and flows referenced in this context.\n Read this first \u2014 IDs below (in node, hierarchy, dependencies) refer to entries here.";
+        break;
+      case "node":
+        pair.key.commentBefore = " Target node: the component you are working on.";
+        break;
+      case "hierarchy":
+        pair.key.commentBefore = " Hierarchy: ancestor modules from root to parent. Context is inherited top-down.";
+        break;
+      case "dependencies":
+        pair.key.commentBefore = " Dependencies: components this node directly depends on.";
+        break;
+    }
   }
-  return stringify(output, { lineWidth: 0 });
+  return doc.toString({ lineWidth: 0 });
 }
 function formatFullContent(files) {
   if (files.length === 0) return "";
@@ -2360,6 +2396,7 @@ async function validate(graph, scope = "all") {
     issues.push(...checkInvalidArtifactConditions(graph));
     issues.push(...await checkContextBudget(graph));
     issues.push(...checkHighFanOut(graph));
+    issues.push(...checkMissingDescriptions(graph));
   }
   issues.push(...checkSchemas(graph));
   issues.push(...checkRelationTargets(graph));
@@ -2370,6 +2407,7 @@ async function validate(graph, scope = "all") {
   issues.push(...checkFlowAspectIds(graph));
   issues.push(...await checkDirectoriesHaveNodeYaml(graph));
   issues.push(...await checkShallowArtifacts(graph));
+  issues.push(...await checkWideNodes(graph));
   issues.push(...checkUnpairedEvents(graph));
   let filtered = issues;
   let nodesScanned = graph.nodes.size;
@@ -2851,6 +2889,29 @@ async function checkShallowArtifacts(graph) {
   }
   return issues;
 }
+async function checkWideNodes(graph) {
+  const issues = [];
+  const maxFiles = graph.config.quality?.max_mapping_source_files ?? 10;
+  const projectRoot = path11.dirname(graph.rootPath);
+  for (const [nodePath, node] of graph.nodes) {
+    if (node.meta.blackbox) continue;
+    const mappingPaths = normalizeMappingPaths(node.meta.mapping);
+    if (mappingPaths.length === 0) continue;
+    const sourceFiles = await expandMappingToFiles(projectRoot, mappingPaths);
+    if (sourceFiles.length <= maxFiles) continue;
+    const filledArtifacts = node.artifacts.filter(
+      (a) => a.content.trim().length >= (graph.config.quality?.min_artifact_length ?? 50)
+    ).length;
+    issues.push({
+      severity: "warning",
+      code: "W017",
+      rule: "wide-node",
+      message: `Node maps ${sourceFiles.length} source files (max: ${maxFiles}) with ${filledArtifacts} artifact(s). Consider splitting into child nodes with focused responsibilities.`,
+      nodePath
+    });
+  }
+  return issues;
+}
 function checkHighFanOut(graph) {
   const issues = [];
   const maxRel = graph.config.quality?.max_direct_relations ?? 10;
@@ -3092,6 +3153,108 @@ function pct(value, total) {
   if (total === 0) return "0%";
   return `${Math.round(value / total * 100)}%`;
 }
+function checkMissingDescriptions(graph) {
+  const issues = [];
+  for (const [nodePath, node] of graph.nodes) {
+    if (!node.meta.description?.trim()) {
+      issues.push({
+        severity: "warning",
+        code: "W016",
+        rule: "missing-description",
+        message: `Node has no description`,
+        nodePath
+      });
+    }
+  }
+  for (const aspect of graph.aspects) {
+    if (!aspect.description?.trim()) {
+      issues.push({
+        severity: "warning",
+        code: "W016",
+        rule: "missing-description",
+        message: `Aspect '${aspect.id}' has no description`
+      });
+    }
+  }
+  for (const flow of graph.flows) {
+    if (!flow.description?.trim()) {
+      issues.push({
+        severity: "warning",
+        code: "W016",
+        rule: "missing-description",
+        message: `Flow '${flow.name}' has no description`
+      });
+    }
+  }
+  return issues;
+}
+
+// src/cli/owner.ts
+import path12 from "path";
+import { access as access2 } from "fs/promises";
+function normalizeForMatch(inputPath) {
+  return inputPath.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+function findOwner(graph, projectRoot, rawPath) {
+  const file = normalizeForMatch(normalizeProjectRelativePath(projectRoot, rawPath));
+  let best = null;
+  for (const [nodePath, node] of graph.nodes) {
+    const mappingPaths = normalizeMappingPaths(node.meta.mapping).map(normalizeForMatch).filter((mappingPath) => mappingPath.length > 0);
+    for (const mappingPath of mappingPaths) {
+      if (file === mappingPath) {
+        return { file, nodePath, mappingPath, direct: true };
+      }
+      if (file.startsWith(mappingPath + "/")) {
+        if (!best || best && mappingPath.length > best.mappingPath.length) {
+          best = { nodePath, mappingPath, exact: false };
+        }
+      }
+    }
+  }
+  return best ? { file, nodePath: best.nodePath, mappingPath: best.mappingPath, direct: false } : { file, nodePath: null };
+}
+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 cwd = process.cwd();
+      const graph = await loadGraph(cwd);
+      const repoRoot = projectRootFromGraph(graph.rootPath);
+      const rawPath = options.file.trim();
+      const absolute = path12.resolve(cwd, rawPath);
+      const repoRelative = path12.relative(repoRoot, absolute).split(path12.sep).join("/");
+      const result = findOwner(graph, repoRoot, repoRelative);
+      if (!result.nodePath) {
+        const absPath = path12.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}
+`);
+        if (result.direct === false && result.mappingPath) {
+          process.stdout.write(
+            `  File has no direct mapping; context comes from ancestor directory ${result.mappingPath}. Use: yg build-context --node ${result.nodePath}
+`
+          );
+        }
+      }
+    } catch (error) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.exit(1);
+    }
+  });
+}
 
 // src/cli/build-context.ts
 function collectRelevantNodePaths(graph, nodePath) {
@@ -3114,10 +3277,32 @@ function collectRelevantNodePaths(graph, nodePath) {
   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/").option("--full", "Include artifact file contents in output").action(async (options) => {
+  program2.command("build-context").description("Assemble a context package for one node").option("--node <node-path>", "Node path relative to .yggdrasil/model/").option("--file <file-path>", "Source file path \u2014 resolves owner node automatically").option("--full", "Include artifact file contents in output").action(async (options) => {
     try {
+      if (!options.node && !options.file) {
+        process.stderr.write("Error: either '--node <path>' or '--file <path>' is required\n");
+        process.exit(1);
+      }
+      if (options.node && options.file) {
+        process.stderr.write("Error: '--node' and '--file' are mutually exclusive\n");
+        process.exit(1);
+      }
       const graph = await loadGraph(process.cwd());
-      const nodePath = options.node.trim().replace(/^\.\//, "").replace(/\/$/, "");
+      let nodePath;
+      if (options.file) {
+        const repoRoot = projectRootFromGraph(graph.rootPath);
+        const result = findOwner(graph, repoRoot, options.file.trim());
+        if (!result.nodePath) {
+          process.stderr.write(`${result.file} -> no graph coverage
+`);
+          process.exit(1);
+        }
+        process.stderr.write(`${result.file} -> ${result.nodePath}
+`);
+        nodePath = result.nodePath;
+      } else {
+        nodePath = options.node.trim().replace(/^\.\//, "").replace(/\/$/, "");
+      }
       const relevantNodes = collectRelevantNodePaths(graph, nodePath);
       const validationResult = await validate(graph, "all");
       const relevantErrors = validationResult.issues.filter(
@@ -3144,22 +3329,31 @@ function registerBuildCommand(program2) {
       const mapOutput = toContextMapOutput(pkg2, graph);
       let output = formatContextYaml(mapOutput);
       if (options.full) {
-        const allFiles = [];
-        const allEntries = [
-          ...Object.values(mapOutput.artifacts.nodes),
-          ...Object.values(mapOutput.artifacts.aspects),
-          ...Object.values(mapOutput.artifacts.flows)
-        ];
         const seen = /* @__PURE__ */ new Set();
-        for (const entry of allEntries) {
-          for (const filePath of entry.files) {
-            if (seen.has(filePath)) continue;
-            seen.add(filePath);
-            const content = await findFileContent(filePath, graph);
-            if (content !== void 0) {
-              allFiles.push({ path: filePath, content });
-            }
+        const allFiles = [];
+        async function collectFile(filePath) {
+          if (seen.has(filePath)) return;
+          seen.add(filePath);
+          const content = await findFileContent(filePath, graph);
+          if (content !== void 0) {
+            allFiles.push({ path: filePath, content });
+          }
+        }
+        for (const aspect of Object.values(mapOutput.glossary.aspects)) {
+          for (const f of aspect.files) await collectFile(f);
+        }
+        for (const flow of Object.values(mapOutput.glossary.flows)) {
+          for (const f of flow.files) await collectFile(f);
+        }
+        for (const f of mapOutput.node.files) await collectFile(f);
+        for (const ancestor of mapOutput.hierarchy) {
+          for (const f of ancestor.files ?? []) await collectFile(f);
+        }
+        for (const dep of mapOutput.dependencies) {
+          for (const ancestor of dep.hierarchy) {
+            for (const f of ancestor.files ?? []) await collectFile(f);
           }
+          for (const f of dep.files ?? []) await collectFile(f);
         }
         output += formatFullContent(allFiles);
       }
@@ -3172,14 +3366,6 @@ function registerBuildCommand(program2) {
   });
 }
 async function findFileContent(filePath, graph) {
-  async function readYamlFromDisk(relativePath) {
-    try {
-      const fullPath = path12.join(graph.rootPath, relativePath);
-      return (await readFile14(fullPath, "utf-8")).trim();
-    } catch {
-      return void 0;
-    }
-  }
   if (filePath.startsWith("model/")) {
     const rest = filePath.slice("model/".length);
     const parts = rest.split("/");
@@ -3187,9 +3373,6 @@ async function findFileContent(filePath, graph) {
     const nodePath = parts.join("/");
     const node = graph.nodes.get(nodePath);
     if (!node) return void 0;
-    if (filename === "yg-node.yaml") {
-      return node.nodeYamlRaw?.trim() ?? await readYamlFromDisk(filePath);
-    }
     const art = node.artifacts.find((a) => a.filename === filename);
     return art?.content;
   }
@@ -3200,9 +3383,6 @@ async function findFileContent(filePath, graph) {
     const filename = parts.slice(1).join("/");
     const aspect = graph.aspects.find((a) => a.id === aspectId);
     if (!aspect) return void 0;
-    if (filename === "yg-aspect.yaml") {
-      return readYamlFromDisk(filePath);
-    }
     const art = aspect.artifacts.find((a) => a.filename === filename);
     return art?.content;
   }
@@ -3213,9 +3393,6 @@ async function findFileContent(filePath, graph) {
     const filename = parts.slice(1).join("/");
     const flow = graph.flows.find((f) => f.path === flowPath);
     if (!flow) return void 0;
-    if (filename === "yg-flow.yaml") {
-      return readYamlFromDisk(filePath);
-    }
     const art = flow.artifacts.find((a) => a.filename === filename);
     return art?.content;
   }
@@ -3271,7 +3448,7 @@ ${errors.length} errors, ${warnings.length} warnings.
 import chalk2 from "chalk";
 
 // src/io/drift-state-store.ts
-import { readFile as readFile15, writeFile as writeFile5, stat as stat5, readdir as readdir6, mkdir as mkdir3, rm as rm2 } from "fs/promises";
+import { readFile as readFile14, writeFile as writeFile5, stat as stat5, readdir as readdir6, mkdir as mkdir3, rm as rm2 } from "fs/promises";
 import path13 from "path";
 import { parse as yamlParse } from "yaml";
 var DRIFT_STATE_DIR = ".drift-state";
@@ -3318,7 +3495,7 @@ async function removeEmptyParents(filePath, stopDir) {
 async function readNodeDriftState(yggRoot, nodePath) {
   try {
     const filePath = nodeStatePath(yggRoot, nodePath);
-    const content = await readFile15(filePath, "utf-8");
+    const content = await readFile14(filePath, "utf-8");
     const parsed = JSON.parse(content);
     return parsed;
   } catch {
@@ -3354,7 +3531,7 @@ async function readDriftState(yggRoot) {
     return {};
   }
   if (driftStat.isFile()) {
-    const content = await readFile15(driftPath, "utf-8");
+    const content = await readFile14(driftPath, "utf-8");
     let raw;
     try {
       raw = JSON.parse(content);
@@ -3386,20 +3563,20 @@ async function readDriftState(yggRoot) {
 }
 
 // src/utils/hash.ts
-import { readFile as readFile16, readdir as readdir7, stat as stat6 } from "fs/promises";
+import { readFile as readFile15, readdir as readdir7, stat as stat6 } from "fs/promises";
 import path14 from "path";
 import { createHash } from "crypto";
 import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
 var ignoreFactory = require2("ignore");
 async function hashFile(filePath) {
-  const content = await readFile16(filePath);
+  const content = await readFile15(filePath);
   return createHash("sha256").update(content).digest("hex");
 }
 async function loadRootGitignoreStack(projectRoot) {
   if (!projectRoot) return [];
   try {
-    const content = await readFile16(path14.join(projectRoot, ".gitignore"), "utf-8");
+    const content = await readFile15(path14.join(projectRoot, ".gitignore"), "utf-8");
     const matcher = ignoreFactory();
     matcher.add(content);
     return [{ basePath: projectRoot, matcher }];
@@ -3474,7 +3651,7 @@ async function hashTrackedFiles(projectRoot, trackedFiles, storedFileData, exclu
 async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, options) {
   let stack = options.gitignoreStack ?? [];
   try {
-    const localContent = await readFile16(path14.join(directoryPath, ".gitignore"), "utf-8");
+    const localContent = await readFile15(path14.join(directoryPath, ".gitignore"), "utf-8");
     const localMatcher = ignoreFactory();
     localMatcher.add(localContent);
     stack = [...stack, { basePath: directoryPath, matcher: localMatcher }];
@@ -3629,7 +3806,7 @@ function collectParticipatingFlows2(graph, node, ancestors) {
 }
 
 // src/core/drift-detector.ts
-import { access as access2 } from "fs/promises";
+import { access as access3 } from "fs/promises";
 import path16 from "path";
 function getChildMappingExclusions(graph, nodePath) {
   const node = graph.nodes.get(nodePath);
@@ -3743,7 +3920,7 @@ async function allPathsMissing(projectRoot, mappingPaths) {
   for (const mp of mappingPaths) {
     const absPath = path16.join(projectRoot, mp);
     try {
-      await access2(absPath);
+      await access3(absPath);
       return false;
     } catch {
     }
@@ -3761,12 +3938,39 @@ async function syncDriftState(graph, 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;
+  let sourceOnlyChange = false;
+  if (previousHash && previousHash !== canonicalHash && existingEntry?.files) {
+    let hasSourceChange = false;
+    let hasGraphChange = false;
+    const yggPrefix = path16.relative(projectRoot, graph.rootPath).split(path16.sep).join("/");
+    for (const [filePath, hash] of Object.entries(fileHashes)) {
+      const storedHash = existingEntry.files[filePath];
+      if (storedHash && storedHash === hash) continue;
+      if (!storedHash || storedHash !== hash) {
+        if (filePath.startsWith(yggPrefix)) {
+          hasGraphChange = true;
+        } else {
+          hasSourceChange = true;
+        }
+      }
+    }
+    for (const storedPath of Object.keys(existingEntry.files)) {
+      if (!(storedPath in fileHashes)) {
+        if (storedPath.startsWith(yggPrefix)) {
+          hasGraphChange = true;
+        } else {
+          hasSourceChange = true;
+        }
+      }
+    }
+    sourceOnlyChange = hasSourceChange && !hasGraphChange;
+  }
   await writeNodeDriftState(graph.rootPath, nodePath, {
     hash: canonicalHash,
     files: fileHashes,
     mtimes: fileMtimes
   });
-  return { previousHash, currentHash: canonicalHash };
+  return { previousHash, currentHash: canonicalHash, sourceOnlyChange };
 }
 
 // src/cli/drift.ts
@@ -3939,13 +4143,20 @@ function registerDriftSyncCommand(program2) {
           }
           continue;
         }
-        const { previousHash, currentHash } = await syncDriftState(graph, np);
+        const { previousHash, currentHash, sourceOnlyChange } = 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)}
 `
         );
+        if (sourceOnlyChange) {
+          process.stderr.write(
+            chalk3.yellow(`  \u26A0 W018: Source files changed but graph artifacts are unchanged for '${np}'.
+`) + chalk3.yellow(`    Update artifacts BEFORE syncing \u2014 drift-sync without artifact update hides staleness.
+`)
+          );
+        }
       }
       if (options.all) {
         const validPaths = new Set(nodesToSync);
@@ -4071,10 +4282,10 @@ function registerTreeCommand(program2) {
       let roots;
       let showProjectName;
       if (options.root?.trim()) {
-        const path20 = options.root.trim().replace(/\/$/, "");
-        const node = graph.nodes.get(path20);
+        const path19 = options.root.trim().replace(/\/$/, "");
+        const node = graph.nodes.get(path19);
         if (!node) {
-          process.stderr.write(`Error: path '${path20}' not found
+          process.stderr.write(`Error: path '${path19}' not found
 `);
           process.exit(1);
         }
@@ -4117,76 +4328,9 @@ function printNode(node, prefix, isLast, depth, maxDepth) {
   }
 }
 
-// src/cli/owner.ts
-import path17 from "path";
-import { access as access3 } from "fs/promises";
-function normalizeForMatch(inputPath) {
-  return inputPath.replace(/\\/g, "/").replace(/\/+$/, "");
-}
-function findOwner(graph, projectRoot, rawPath) {
-  const file = normalizeForMatch(normalizeProjectRelativePath(projectRoot, rawPath));
-  let best = null;
-  for (const [nodePath, node] of graph.nodes) {
-    const mappingPaths = normalizeMappingPaths(node.meta.mapping).map(normalizeForMatch).filter((mappingPath) => mappingPath.length > 0);
-    for (const mappingPath of mappingPaths) {
-      if (file === mappingPath) {
-        return { file, nodePath, mappingPath, direct: true };
-      }
-      if (file.startsWith(mappingPath + "/")) {
-        if (!best || best && mappingPath.length > best.mappingPath.length) {
-          best = { nodePath, mappingPath, exact: false };
-        }
-      }
-    }
-  }
-  return best ? { file, nodePath: best.nodePath, mappingPath: best.mappingPath, direct: false } : { file, nodePath: null };
-}
-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 cwd = process.cwd();
-      const graph = await loadGraph(cwd);
-      const repoRoot = projectRootFromGraph(graph.rootPath);
-      const rawPath = options.file.trim();
-      const absolute = path17.resolve(cwd, rawPath);
-      const repoRelative = path17.relative(repoRoot, absolute).split(path17.sep).join("/");
-      const result = findOwner(graph, repoRoot, repoRelative);
-      if (!result.nodePath) {
-        const absPath = path17.resolve(repoRoot, result.file);
-        let exists = true;
-        try {
-          await access3(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}
-`);
-        if (result.direct === false && result.mappingPath) {
-          process.stdout.write(
-            `  File has no direct mapping; context comes from ancestor directory ${result.mappingPath}. Use: yg build-context --node ${result.nodePath}
-`
-          );
-        }
-      }
-    } catch (error) {
-      process.stderr.write(`Error: ${error.message}
-`);
-      process.exit(1);
-    }
-  });
-}
-
 // src/core/dependency-resolver.ts
 import { execSync } from "child_process";
-import path18 from "path";
+import path17 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) {
@@ -4263,7 +4407,7 @@ function registerDepsCommand(program2) {
 // src/core/graph-from-git.ts
 import { mkdtemp, rm as rm3 } from "fs/promises";
 import { tmpdir } from "os";
-import path19 from "path";
+import path18 from "path";
 import { execSync as execSync2 } from "child_process";
 async function loadGraphFromRef(projectRoot, ref = "HEAD") {
   const yggPath = ".yggdrasil";
@@ -4274,8 +4418,8 @@ async function loadGraphFromRef(projectRoot, ref = "HEAD") {
     return null;
   }
   try {
-    tmpDir = await mkdtemp(path19.join(tmpdir(), "ygg-git-"));
-    const archivePath = path19.join(tmpDir, "archive.tar");
+    tmpDir = await mkdtemp(path18.join(tmpdir(), "ygg-git-"));
+    const archivePath = path18.join(tmpDir, "archive.tar");
     execSync2(`git archive ${ref} ${yggPath} -o "${archivePath}"`, {
       cwd: projectRoot,
       stdio: "pipe"
@@ -4345,14 +4489,14 @@ function buildTransitiveChains(targetNode, direct, allDependents, reverse) {
   }
   const chains = [];
   for (const node of transitiveOnly) {
-    const path20 = [];
+    const path19 = [];
     let current = node;
     while (current) {
-      path20.unshift(current);
+      path19.unshift(current);
       current = parent.get(current);
     }
-    if (path20.length >= 3) {
-      chains.push(path20.slice(1).map((p) => `<- ${p}`).join(" "));
+    if (path19.length >= 3) {
+      chains.push(path19.slice(1).map((p) => `<- ${p}`).join(" "));
     }
   }
   return chains.sort();
@@ -4396,14 +4540,14 @@ function collectIndirectDependents(graph, directlyAffected) {
     }
     for (const [node] of parent) {
       if (directSet.has(node)) continue;
-      const path20 = [node];
+      const path19 = [node];
       let current = node;
       while (parent.has(current)) {
         current = parent.get(current);
-        path20.push(current);
+        path19.push(current);
       }
-      const chain = path20.map((p) => `<- ${p}`).join(" ");
-      const depth = path20.length;
+      const chain = path19.map((p) => `<- ${p}`).join(" ");
+      const depth = path19.length;
       const existing = bestChain.get(node);
       if (!existing || depth < existing.depth) {
         bestChain.set(node, { chain, depth });
@@ -4600,23 +4744,39 @@ Total scope: ${sorted.length + indirectPaths.length} nodes
   }
 }
 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("--method <name>", "Filter impact to dependents consuming a specific method (requires --node)").option("--simulate", "Simulate context package impact (compare HEAD vs current)").action(
+  program2.command("impact").description("Show reverse dependency impact for a node, aspect, or flow").option("--node <path>", "Node path relative to .yggdrasil/model/").option("--file <file-path>", "Source file path \u2014 resolves owner node automatically").option("--aspect <id>", "Aspect id (directory path under aspects/)").option("--flow <name>", "Flow name (directory name under flows/)").option("--method <name>", "Filter impact to dependents consuming a specific method (requires --node or --file)").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 (options.node && options.file) {
+          process.stderr.write("Error: '--node' and '--file' are mutually exclusive\n");
+          process.exit(1);
+        }
+        const modeCount = [options.node || options.file, options.aspect, options.flow].filter(Boolean).length;
         if (modeCount === 0) {
           process.stderr.write(
-            "Error: one of --node, --aspect, or --flow is required\n"
+            "Error: one of --node, --file, --aspect, or --flow is required\n"
           );
           process.exit(1);
         }
         if (modeCount > 1) {
           process.stderr.write(
-            "Error: --node, --aspect, and --flow are mutually exclusive\n"
+            "Error: --node/--file, --aspect, and --flow are mutually exclusive\n"
           );
           process.exit(1);
         }
         const graph = await loadGraph(process.cwd());
+        if (options.file) {
+          const repoRoot = projectRootFromGraph(graph.rootPath);
+          const result = findOwner(graph, repoRoot, options.file.trim());
+          if (!result.nodePath) {
+            process.stderr.write(`${result.file} -> no graph coverage
+`);
+            process.exit(1);
+          }
+          process.stderr.write(`${result.file} -> ${result.nodePath}
+`);
+          options.node = result.nodePath;
+        }
         if (options.aspect) {
           await handleAspectImpact(graph, options.aspect.trim(), options.simulate);
           return;
@@ -4845,6 +5005,7 @@ function registerFlowsCommand(program2) {
           participants: flow.nodes.length,
           nodes: flow.nodes.sort()
         };
+        if (flow.description) entry.description = flow.description;
         if (flow.aspects && flow.aspects.length > 0) entry.aspects = flow.aspects;
         return entry;
       });