@chrisdudek/yg 1.3.0 → 1.4.0

package/dist/bin.js

@@ -92,11 +92,29 @@ WHEN UNSURE: ask the user. Never guess. Never assume.
 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 Worked on a mapped file without running \`yg owner\` + \`yg build-context\` first \u2014 whether reading to understand, planning, or modifying.
+- \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.
@@ -206,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>\`
@@ -308,6 +327,8 @@ Three artifacts capture node knowledge at three levels:
 - **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. 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.
@@ -343,6 +364,14 @@ When a node follows an aspect's pattern with exceptions, record exceptions in \`
 
 **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\`
@@ -379,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.
@@ -405,7 +435,7 @@ yg journal-archive                  Archive consolidated journal entries.
 | 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");
+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";
@@ -862,6 +892,7 @@ async function parseNodeYaml(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(),
@@ -869,9 +900,37 @@ async function parseNodeYaml(filePath) {
     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)) {
@@ -1002,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) {
@@ -1024,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
   };
 }
@@ -1538,6 +1608,10 @@ Consumes: ${relation.consumes.join(", ")}`;
 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 += `
 
@@ -1613,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") {
@@ -1644,6 +1718,7 @@ async function validate(graph, scope = "all") {
     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));
@@ -2286,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;
@@ -2502,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);
@@ -2533,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 }];
@@ -2573,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,
@@ -2621,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 }];
@@ -2642,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,
@@ -3642,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;
@@ -3673,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)) {
@@ -3691,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})
 `);
           }
         }
@@ -3751,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
@@ -3780,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));
@@ -3833,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";
@@ -3841,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 : [];