@chrisdudek/yg 1.2.0 → 1.4.0

package/dist/bin.js

@@ -21,6 +21,7 @@ node_types:
   - name: module
   - name: service
   - name: library
+  - name: infrastructure
 
 artifacts:
   responsibility.md:
@@ -30,29 +31,11 @@ artifacts:
   interface.md:
     required:
       when: has_incoming_relations
-    description: "Public API \u2014 methods, parameters, return types, contracts"
+    description: "Public API \u2014 methods, parameters, return types, contracts, failure modes, exposed data structures"
     structural_context: true
-  logic.md:
+  internals.md:
     required: never
-    description: "Algorithmic flow, control flow, branching logic, decision trees \u2014 the 'how' of execution"
-  constraints.md:
-    required: never
-    description: "Validation rules, business rules, invariants"
-    structural_context: true
-  errors.md:
-    required:
-      when: has_incoming_relations
-    description: "Failure modes, edge cases, error conditions, recovery behavior"
-    structural_context: true
-  model.md:
-    required: never
-    description: "Data structures, schemas, entities, type definitions \u2014 the shape of data this node owns or manages"
-  state.md:
-    required: never
-    description: "State machines, lifecycle, transitions"
-  decisions.md:
-    required: never
-    description: "Local design decisions and rationale \u2014 choices specific to this node, not system-wide"
+    description: "How the node works and why \u2014 algorithms, business rules, state machines, design decisions with rejected alternatives"
 
 quality:
   min_artifact_length: 50
@@ -77,11 +60,12 @@ Yggdrasil is persistent semantic memory stored in \`.yggdrasil/\`. It maps the r
 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.
+  The context package is your primary source of ARCHITECTURAL understanding:
+  intent, constraints, relations, rationale. For IMPLEMENTATION precision
+  (exact behavior, error handling, await patterns, edge cases) \u2014 verify
+  against source code. Aspects describe intended patterns; individual
+  implementations may deviate.
   If the context package seems insufficient \u2014 enrich the graph.
-  Do not bypass it.
 
 AFTER modifying:
   3. Update graph artifacts to reflect changes
@@ -102,31 +86,42 @@ WHEN UNSURE: ask the user. Never guess. Never assume.
 
 ### Five Core Rules
 
-1. **Graph first.** Before reading, researching, planning, or modifying mapped files, run \`yg owner\` and \`yg build-context\`. Always. The context package \u2014 not raw source \u2014 is your primary source of understanding.
+1. **Graph first.** Before reading, researching, planning, or modifying mapped files, run \`yg owner\` and \`yg build-context\`. Always. The context package is your primary source of architectural understanding. For implementation-level precision (exact behavior, error paths, edge cases) \u2014 verify against source code after loading the context package.
 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.
 
+### Recognizing Graph-Required Actions
+
+What matters is the ACTION you are performing, not what instructed it. If the action involves understanding mapped code, the graph protocol applies \u2014 whether the instruction came from a skill, a plan, a user message, a workflow step, or your own initiative.
+
+**Actions that require \`yg owner\` + \`yg build-context\` first:**
+
+- 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 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
+
 ### Failure States
 
 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 Worked on a mapped file without running \`yg owner\` + \`yg build-context\` first \u2014 regardless of what instructed the action (skill, plan, user request, workflow step).
+- \u274C Modified source code without updating graph artifacts in the same response, 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 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 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 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
 
@@ -201,7 +196,7 @@ 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, constraints, decisions, interface, logic
+3. Create nodes with full artifacts \u2014 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)
@@ -229,6 +224,7 @@ Per area checklist:
 - [ ] 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
+- [ ] 6b. For each aspect on the node: identify 2-5 code anchors (function names, constants) that evidence the pattern \u2192 add to \`node.yaml\` \`anchors\` field
 - [ ] 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>\`
@@ -238,7 +234,8 @@ Per area checklist:
 - 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\`.
+- 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
 
@@ -266,6 +263,27 @@ Always ask the user before resolving drift. Never auto-resolve.
 
 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 \`aspect_exceptions\` in \`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.
@@ -294,9 +312,26 @@ Key facts:
 - **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.
 
+**Node type guidance:**
+
+- \`module\` \u2014 business logic unit with clear domain responsibility
+- \`service\` \u2014 component providing functionality to other nodes
+- \`library\` \u2014 shared utility code with no domain knowledge
+- \`infrastructure\` \u2014 guards, resolvers, middleware, interceptors, validators that intercept or modify request flow. These affect blast radius of changes but are invisible in call graphs. Map them to make blast radius analysis accurate. Key signal: code that runs WITHOUT being explicitly called by business logic (e.g., NestJS guards, Express middleware, GraphQL resolvers).
+
+### Artifact Structure
+
+Three artifacts capture node knowledge at three levels:
+
+- **responsibility.md** (always required) \u2014 WHAT: identity, boundaries, what the node is NOT responsible for.
+- **interface.md** (required when node has consumers) \u2014 HOW TO USE: public methods, parameters, return types, contracts, failure modes, exposed data structures. Everything another node needs to interact with this one.
+- **internals.md** (optional, highest value for cross-module nodes) \u2014 HOW IT WORKS + WHY: algorithms, control flow, business rules, invariants, state machines, lifecycle, and design decisions with rejected alternatives. Use sections within the file: ## Logic, ## Constraints, ## State, ## Decisions (with "Chose X over Y because Z" format).
+
+**Enrichment priority (when adding incrementally):** \`interface.md\` first (highest cross-module ROI \u2014 contracts enable other nodes to reason about interactions), then \`responsibility.md\` (identity and boundaries), then \`internals.md\` (depth for complex nodes). A node with only \`interface.md\` provides more cross-module value than one with only \`internals.md\`.
+
 ### 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.
+Run \`yg build-context --node <path>\` to get the deterministic context package for a node. The package assembles global config, hierarchy, own artifacts, aspects, and relational context. It is your architectural map. For implementation-level claims (exact call patterns, error handling, await vs fire-and-forget) \u2014 verify against source code. If the package is insufficient, enrich the graph.
 
 ### Information Routing
 
@@ -307,7 +342,7 @@ When you encounter information, route it to the correct location:
 - **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.
+- **Decision (why + why NOT):** one node \u2192 Decisions section of \`internals.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. If the rationale is unknown: record the decision with "rationale: unknown" and note what CAN be observed from the code. Never invent a plausible-sounding rationale.
 
 ### Creating Aspects
 
@@ -325,6 +360,18 @@ Test: "Does this requirement apply to more than one node?" Yes \u2192 aspect. No
 - **Architectural:** Structural patterns with rationale (e.g., dual-rollback on provider failure, idempotency via key generation, fire-and-forget dispatch)
 - **Concurrency:** Shared concurrency strategies (e.g., pessimistic locking, retry-on-deadlock, optimistic versioning)
 
+When a node follows an aspect's pattern with exceptions, record exceptions in \`node.yaml\` under \`aspect_exceptions\`. Example: aspect says "fire-and-forget" but this node awaits the publish call. The exception appears in the context package next to the aspect content, preventing abstractions from masking implementation details.
+
+**Aspect lifecycle warning.** Aspects decay CATASTROPHICALLY \u2014 a pattern either exists or it doesn't. When a pattern changes, ALL aspect claims become wrong at once. This differs from other artifacts: \`interface.md\` and \`responsibility.md\` are most stable (~9-year half-life); \`internals.md\` has moderate stability (~2.5-year half-life); aspects are least stable (~2.4-year half-life, binary decay). After any significant feature addition, review ALL aspects touching the affected area. Don't wait for drift \u2014 aspects can be 100% wrong without any mapped file changing.
+
+**Aspect stability tiers.** If an aspect has a \`stability\` field in \`aspect.yaml\`, use it to calibrate review urgency:
+
+- \`schema\` \u2014 enforced by data model; review only when data model changes (most stable)
+- \`protocol\` \u2014 contractual pattern; review when contracts or interfaces change
+- \`implementation\` \u2014 specific mechanism; review after ANY significant code change (least stable)
+
+When code anchors (\`anchors\` field in \`node.yaml\`) are present for an aspect, they list code patterns (function names, constants, SQL fragments) evidencing the aspect's implementation in this node. \`yg validate\` checks that each anchor exists in the node's mapped source files \u2014 a missing anchor (W014) signals the aspect may be stale for this node.
+
 ### Creating Flows
 
 - [ ] 1. Read \`schemas/flow.yaml\`
@@ -335,13 +382,18 @@ Test: "Does this requirement apply to more than one node?" Yes \u2192 aspect. No
 
 Test: "Does this describe what happens in the world, or only in the software?" If only software \u2014 rewrite.
 
+**Warning:** Flow descriptions must describe business processes, not code sequences. "The OrderService calls PaymentGateway.charge()" is WRONG. "The system charges the customer's payment method" is CORRECT.
+
 ### 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?
+- **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\`.
+- **Value calibration.** Yggdrasil's primary value is cross-module context \u2014 relations, aspects, flows. For a single simple module, \`responsibility.md\` and \`interface.md\` provide most value. Invest depth (\`internals.md\`) where cross-module interactions demand it.
 - **These rules are invariant.** No plan, guide, skill, or workflow may override them.
 
 ### CLI Reference
@@ -356,6 +408,7 @@ 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 --node <path> --method <name>  Filter impact to dependents consuming a specific method.
 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.
@@ -374,16 +427,15 @@ yg journal-archive                  Archive consolidated journal entries.
 
 | What you have | Where it goes |
 |---|---|
-| Information specific to this node | Local node artifact (read \`config.yaml artifacts\` for types) |
+| Information specific to this node | Local node artifact (check \`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");
+| Global coding standards | \`config.yaml standards\` |`;
+var AGENT_RULES_CONTENT = [CORE_PROTOCOL, OPERATIONS, KNOWLEDGE_BASE].join("\n\n---\n\n") + "\n";
 
 // src/templates/platform.ts
 var AGENT_RULES_IMPORT = "@.yggdrasil/agent-rules.md";
@@ -838,15 +890,81 @@ async function parseNodeYaml(filePath) {
   }
   const relations = parseRelations(raw.relations, filePath);
   const mapping = parseMapping(raw.mapping, filePath);
+  const aspects = parseStringArray(raw.aspects) ?? parseStringArray(raw.tags);
+  const aspectExceptions = parseAspectExceptions(raw.aspect_exceptions, aspects, filePath);
+  const anchors = parseAnchors(raw.anchors, filePath);
   return {
     name: raw.name.trim(),
     type: raw.type.trim(),
-    aspects: parseStringArray(raw.aspects) ?? parseStringArray(raw.tags),
+    aspects,
+    aspect_exceptions: aspectExceptions,
     blackbox: raw.blackbox ?? false,
     relations: relations.length > 0 ? relations : void 0,
-    mapping
+    mapping,
+    anchors
   };
 }
+function parseAnchors(raw, filePath) {
+  if (raw === void 0 || raw === null) return void 0;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(
+      `node.yaml at ${filePath}: 'anchors' must be an object mapping aspect ids to arrays of strings`
+    );
+  }
+  const obj = raw;
+  const entries = Object.entries(obj);
+  if (entries.length === 0) return void 0;
+  const result = {};
+  for (const [key, value] of entries) {
+    if (!Array.isArray(value) || value.length === 0) {
+      throw new Error(
+        `node.yaml at ${filePath}: 'anchors.${key}' must be a non-empty array of strings`
+      );
+    }
+    const strings = value.filter((v) => typeof v === "string");
+    if (strings.length === 0) {
+      throw new Error(
+        `node.yaml at ${filePath}: 'anchors.${key}' must be a non-empty array of strings`
+      );
+    }
+    result[key] = strings;
+  }
+  return result;
+}
+function parseAspectExceptions(raw, aspects, filePath) {
+  if (raw === void 0 || raw === null) return void 0;
+  if (!Array.isArray(raw)) {
+    throw new Error(`node.yaml at ${filePath}: 'aspect_exceptions' must be an array`);
+  }
+  if (raw.length === 0) return void 0;
+  const aspectSet = new Set(aspects ?? []);
+  const result = [];
+  for (let i = 0; i < raw.length; i++) {
+    const item = raw[i];
+    if (typeof item !== "object" || item === null) {
+      throw new Error(`node.yaml at ${filePath}: aspect_exceptions[${i}] must be an object`);
+    }
+    const obj = item;
+    if (typeof obj.aspect !== "string" || obj.aspect.trim() === "") {
+      throw new Error(
+        `node.yaml at ${filePath}: aspect_exceptions[${i}].aspect must be a non-empty string`
+      );
+    }
+    if (typeof obj.note !== "string" || obj.note.trim() === "") {
+      throw new Error(
+        `node.yaml at ${filePath}: aspect_exceptions[${i}].note must be a non-empty string`
+      );
+    }
+    const aspectId = obj.aspect.trim();
+    if (!aspectSet.has(aspectId)) {
+      throw new Error(
+        `node.yaml at ${filePath}: aspect_exceptions[${i}].aspect "${aspectId}" is not in this node's aspects list`
+      );
+    }
+    result.push({ aspect: aspectId, note: obj.note.trim() });
+  }
+  return result.length > 0 ? result : void 0;
+}
 function parseStringArray(val) {
   if (!Array.isArray(val)) return void 0;
   const arr = val.filter((v) => typeof v === "string");
@@ -943,6 +1061,7 @@ async function readArtifacts(dirPath, excludeFiles = ["node.yaml"], includeFiles
 }
 
 // src/io/aspect-parser.ts
+var VALID_STABILITY_VALUES = ["schema", "protocol", "implementation"];
 async function parseAspect(aspectDir, aspectYamlPath, id) {
   const idTrimmed = id?.trim() ?? "";
   if (!idTrimmed) {
@@ -965,11 +1084,21 @@ async function parseAspect(aspectDir, aspectYamlPath, id) {
     }
     implies = raw.implies.filter((t) => typeof t === "string");
   }
+  let stability;
+  if (raw.stability !== void 0) {
+    if (typeof raw.stability !== "string" || !VALID_STABILITY_VALUES.includes(raw.stability)) {
+      throw new Error(
+        `Aspect file ${aspectYamlPath}: 'stability' must be one of: ${VALID_STABILITY_VALUES.join(", ")}`
+      );
+    }
+    stability = raw.stability;
+  }
   return {
     name: raw.name.trim(),
     id: idTrimmed,
     description,
     implies,
+    stability,
     artifacts
   };
 }
@@ -1292,7 +1421,8 @@ async function buildContext(graph, nodePath) {
   }
   const aspectsToInclude = resolveAspects(allAspectIds, graph.aspects);
   for (const aspect of aspectsToInclude) {
-    layers.push(buildAspectLayer(aspect));
+    const exception = node.meta.aspect_exceptions?.find((e) => e.aspect === aspect.id);
+    layers.push(buildAspectLayer(aspect, exception?.note));
   }
   const fullText = layers.map((l) => l.content).join("\n\n");
   const tokenCount = estimateTokens(fullText);
@@ -1475,9 +1605,18 @@ Consumes: ${relation.consumes.join(", ")}`;
     attrs
   };
 }
-function buildAspectLayer(aspect) {
-  const content = aspect.artifacts.map((a) => `### ${a.filename}
+function buildAspectLayer(aspect, exceptionNote) {
+  let content = aspect.artifacts.map((a) => `### ${a.filename}
 ${a.content}`).join("\n\n");
+  if (aspect.stability) {
+    content += `
+**Stability tier:** ${aspect.stability}`;
+  }
+  if (exceptionNote) {
+    content += `
+
+\u26A0 **Exception for this node:** ${exceptionNote}`;
+  }
   return {
     type: "aspects",
     label: `${aspect.name} (aspect: ${aspect.id})`,
@@ -1548,7 +1687,7 @@ function collectEffectiveAspectIds(graph, nodePath) {
 }
 
 // src/core/validator.ts
-import { readdir as readdir4 } from "fs/promises";
+import { readdir as readdir4, readFile as readFile11, stat as stat3 } from "fs/promises";
 import path9 from "path";
 var RESERVED_DIRS = /* @__PURE__ */ new Set();
 async function validate(graph, scope = "all") {
@@ -1578,6 +1717,8 @@ async function validate(graph, scope = "all") {
     issues.push(...checkImpliedAspectsExist(graph));
     issues.push(...checkImpliesNoCycles(graph));
     issues.push(...checkRequiredAspectsCoverage(graph));
+    issues.push(...checkAspectExceptions(graph));
+    issues.push(...await checkAnchorPresence(graph));
     issues.push(...checkRequiredArtifacts(graph));
     issues.push(...checkInvalidArtifactConditions(graph));
     issues.push(...await checkContextBudget(graph));
@@ -1824,6 +1965,24 @@ function checkRequiredAspectsCoverage(graph) {
   }
   return issues;
 }
+function checkAspectExceptions(graph) {
+  const issues = [];
+  for (const [nodePath, node] of graph.nodes) {
+    for (const exception of node.meta.aspect_exceptions ?? []) {
+      const nodeAspects = node.meta.aspects ?? [];
+      if (!nodeAspects.includes(exception.aspect)) {
+        issues.push({
+          severity: "error",
+          code: "E018",
+          rule: "invalid-aspect-exception",
+          message: `aspect_exceptions references aspect '${exception.aspect}' which is not in this node's aspects list (${nodeAspects.join(", ") || "none"})`,
+          nodePath
+        });
+      }
+    }
+  }
+  return issues;
+}
 function checkNoCycles(graph) {
   const WHITE = 0;
   const GRAY = 1;
@@ -2202,6 +2361,81 @@ async function checkDirectoriesHaveNodeYaml(graph) {
   }
   return issues;
 }
+async function expandMappingToFiles(projectRoot, mappingPaths) {
+  const files = [];
+  async function collectFiles(absPath) {
+    try {
+      const s = await stat3(absPath);
+      if (s.isFile()) {
+        files.push(absPath);
+      } else if (s.isDirectory()) {
+        const entries = await readdir4(absPath, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+          const entryPath = path9.join(absPath, entry.name);
+          if (entry.isFile()) {
+            files.push(entryPath);
+          } else if (entry.isDirectory()) {
+            await collectFiles(entryPath);
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  for (const mp of mappingPaths) {
+    await collectFiles(path9.join(projectRoot, mp));
+  }
+  return files;
+}
+async function checkAnchorPresence(graph) {
+  const issues = [];
+  const projectRoot = path9.dirname(graph.rootPath);
+  for (const [nodePath, node] of graph.nodes) {
+    const anchors = node.meta.anchors;
+    if (!anchors) continue;
+    const nodeAspects = new Set(node.meta.aspects ?? []);
+    for (const aspectId of Object.keys(anchors)) {
+      if (!nodeAspects.has(aspectId)) {
+        issues.push({
+          severity: "error",
+          code: "E019",
+          rule: "invalid-anchor-ref",
+          message: `anchors references aspect '${aspectId}' which is not in this node's aspects list (${[...nodeAspects].join(", ") || "none"})`,
+          nodePath
+        });
+      }
+    }
+    const mappingPaths = normalizeMappingPaths(node.meta.mapping);
+    if (mappingPaths.length === 0) continue;
+    const sourceFiles = await expandMappingToFiles(projectRoot, mappingPaths);
+    if (sourceFiles.length === 0) continue;
+    const fileContents = [];
+    for (const filePath of sourceFiles) {
+      try {
+        const content = await readFile11(filePath, "utf-8");
+        fileContents.push(content);
+      } catch {
+      }
+    }
+    for (const [aspectId, anchorList] of Object.entries(anchors)) {
+      if (!nodeAspects.has(aspectId)) continue;
+      for (const anchor of anchorList) {
+        const found = fileContents.some((content) => content.includes(anchor));
+        if (!found) {
+          issues.push({
+            severity: "warning",
+            code: "W014",
+            rule: "anchor-not-found",
+            message: `Anchor '${anchor}' for aspect '${aspectId}' not found in mapped source files`,
+            nodePath
+          });
+        }
+      }
+    }
+  }
+  return issues;
+}
 async function checkContextBudget(graph) {
   const issues = [];
   const warningThreshold = graph.config.quality?.context_budget.warning ?? 1e4;
@@ -2418,13 +2652,13 @@ ${errors.length} errors, ${warnings.length} warnings.
 import chalk2 from "chalk";
 
 // src/io/drift-state-store.ts
-import { readFile as readFile11, writeFile as writeFile3 } from "fs/promises";
+import { readFile as readFile12, writeFile as writeFile3 } from "fs/promises";
 import path10 from "path";
 import { parse as yamlParse } from "yaml";
 var DRIFT_STATE_FILE = ".drift-state";
 async function readDriftState(yggRoot) {
   try {
-    const content = await readFile11(path10.join(yggRoot, DRIFT_STATE_FILE), "utf-8");
+    const content = await readFile12(path10.join(yggRoot, DRIFT_STATE_FILE), "utf-8");
     let raw;
     try {
       raw = JSON.parse(content);
@@ -2449,20 +2683,20 @@ async function writeDriftState(yggRoot, state) {
 }
 
 // src/utils/hash.ts
-import { readFile as readFile12, readdir as readdir5, stat as stat3 } from "fs/promises";
+import { readFile as readFile13, readdir as readdir5, stat as stat4 } from "fs/promises";
 import path11 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 readFile12(filePath);
+  const content = await readFile13(filePath);
   return createHash("sha256").update(content).digest("hex");
 }
 async function loadRootGitignoreStack(projectRoot) {
   if (!projectRoot) return [];
   try {
-    const content = await readFile12(path11.join(projectRoot, ".gitignore"), "utf-8");
+    const content = await readFile13(path11.join(projectRoot, ".gitignore"), "utf-8");
     const matcher = ignoreFactory();
     matcher.add(content);
     return [{ basePath: projectRoot, matcher }];
@@ -2489,7 +2723,7 @@ async function hashTrackedFiles(projectRoot, trackedFiles, storedFileData, exclu
   for (const tf of trackedFiles) {
     const absPath = path11.join(projectRoot, tf.path);
     try {
-      const st = await stat3(absPath);
+      const st = await stat4(absPath);
       if (st.isDirectory()) {
         const dirEntries = await collectDirectoryFilePaths(absPath, absPath, {
           projectRoot,
@@ -2537,7 +2771,7 @@ async function hashTrackedFiles(projectRoot, trackedFiles, storedFileData, exclu
 async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, options) {
   let stack = options.gitignoreStack ?? [];
   try {
-    const localContent = await readFile12(path11.join(directoryPath, ".gitignore"), "utf-8");
+    const localContent = await readFile13(path11.join(directoryPath, ".gitignore"), "utf-8");
     const localMatcher = ignoreFactory();
     localMatcher.add(localContent);
     stack = [...stack, { basePath: directoryPath, matcher: localMatcher }];
@@ -2558,7 +2792,7 @@ async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, optio
       gitignoreStack: stack
     }))),
     Promise.all(files.map(async (f) => {
-      const fileStat = await stat3(f);
+      const fileStat = await stat4(f);
       return {
         relPath: path11.relative(rootDirectoryPath, f),
         absPath: f,
@@ -3558,7 +3792,7 @@ Total scope: ${sorted.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("--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("--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(
     async (options) => {
       try {
         const modeCount = [options.node, options.aspect, options.flow].filter(Boolean).length;
@@ -3589,11 +3823,56 @@ function registerImpactCommand(program2) {
 `);
           process.exit(1);
         }
+        if (options.method && !options.node) {
+          process.stderr.write("Error: --method requires --node\n");
+          process.exit(1);
+        }
         const { direct, allDependents, reverse, relationFrom } = collectReverseDependents(
           graph,
           nodePath
         );
-        const chains = buildTransitiveChains(nodePath, direct, allDependents, reverse);
+        const methodFilter = options.method?.trim();
+        let filteredDirect = direct;
+        let filteredAllDependents = allDependents;
+        if (methodFilter) {
+          filteredDirect = direct.filter((dep) => {
+            const rel = relationFrom.get(`${dep}->${nodePath}`);
+            return rel?.consumes?.includes(methodFilter) || !rel?.consumes?.length;
+          });
+          const filteredSet = new Set(filteredDirect);
+          filteredAllDependents = allDependents.filter((dep) => filteredSet.has(dep));
+        }
+        const chains = buildTransitiveChains(nodePath, filteredDirect, filteredAllDependents, reverse);
+        const eventDependents = [];
+        for (const [np, n] of graph.nodes) {
+          for (const rel of n.meta.relations ?? []) {
+            if (rel.target === nodePath && (rel.type === "emits" || rel.type === "listens")) {
+              eventDependents.push({
+                path: np,
+                type: rel.type,
+                eventName: rel.event_name ?? n.meta.name
+              });
+            }
+          }
+        }
+        const targetNode = graph.nodes.get(nodePath);
+        for (const rel of targetNode.meta.relations ?? []) {
+          if (rel.type === "emits") {
+            const eventName = rel.event_name ?? rel.target;
+            for (const [np, n] of graph.nodes) {
+              if (np === nodePath) continue;
+              for (const r of n.meta.relations ?? []) {
+                if (r.type === "listens" && r.target === rel.target) {
+                  eventDependents.push({
+                    path: np,
+                    type: "listens",
+                    eventName: r.event_name ?? eventName
+                  });
+                }
+              }
+            }
+          }
+        }
         const flows = [];
         for (const flow of graph.flows) {
           if (flow.nodes.includes(nodePath)) {
@@ -3607,17 +3886,25 @@ function registerImpactCommand(program2) {
             aspectsInScope.push(aspect.name);
           }
         }
-        process.stdout.write(`Impact of changes in ${nodePath}:
+        const methodLabel = methodFilter ? ` (method: ${methodFilter})` : "";
+        process.stdout.write(`Impact of changes in ${nodePath}${methodLabel}:
 
 `);
         process.stdout.write("Directly dependent:\n");
-        if (direct.length === 0) {
+        if (filteredDirect.length === 0) {
           process.stdout.write("  (none)\n");
         } else {
-          for (const dep of direct) {
+          for (const dep of filteredDirect) {
             const rel = relationFrom.get(`${dep}->${nodePath}`);
-            const annot = rel?.consumes?.length ? ` (${rel.type}, you consume: ${rel.consumes.join(", ")})` : rel ? ` (${rel.type})` : "";
+            const annot = rel?.consumes?.length ? ` (${rel.type}, consumes: ${rel.consumes.join(", ")})` : rel ? ` (${rel.type})` : "";
             process.stdout.write(`  <- ${dep}${annot}
+`);
+          }
+        }
+        if (eventDependents.length > 0 && !methodFilter) {
+          process.stdout.write("\nEvent-connected:\n");
+          for (const { path: p, type, eventName } of eventDependents.sort((a, b) => a.path.localeCompare(b.path))) {
+            process.stdout.write(`  ${p} (${type}: ${eventName})
 `);
           }
         }
@@ -3667,7 +3954,7 @@ Flows: ${flows.length > 0 ? flows.join(", ") : "(none)"}
 `);
           }
         }
-        const allAffected = /* @__PURE__ */ new Set([...allDependents, ...descendants]);
+        const allAffected = /* @__PURE__ */ new Set([...filteredAllDependents, ...descendants, ...eventDependents.map((e) => e.path)]);
         process.stdout.write(
           `
 Total scope: ${allAffected.size} nodes, ${flows.length} flows, ${aspectsInScope.length} aspects
@@ -3696,6 +3983,7 @@ function registerAspectsCommand(program2) {
         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;
+        if (aspect.stability) entry.stability = aspect.stability;
         return entry;
       });
       process.stdout.write(yamlStringify(output));
@@ -3749,7 +4037,7 @@ function registerFlowsCommand(program2) {
 }
 
 // src/io/journal-store.ts
-import { readFile as readFile13, writeFile as writeFile4, mkdir as mkdir3, rename, access as access3 } from "fs/promises";
+import { readFile as readFile14, 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";
@@ -3757,7 +4045,7 @@ var ARCHIVE_DIR = "journals-archive";
 async function readJournal(yggRoot) {
   const filePath = path17.join(yggRoot, JOURNAL_FILE);
   try {
-    const content = await readFile13(filePath, "utf-8");
+    const content = await readFile14(filePath, "utf-8");
     const raw = parseYaml6(content);
     const entries = raw.entries ?? [];
     return Array.isArray(entries) ? entries : [];