@chrisdudek/yg 1.0.0 → 1.1.0

package/dist/bin.js

@@ -105,7 +105,7 @@ WHEN UNSURE: ask the user. Never guess. Never assume.
 1. **Graph first.** Before reading, researching, planning, or modifying mapped files, run \`yg owner\` and \`yg build-context\`. Always. The context package \u2014 not raw source \u2014 is your primary source of understanding.
 2. **Code and graph are one.** Code changed \u2192 graph updated in the same response. Graph changed \u2192 source verified in the same response. No exceptions.
 3. **Never invent why.** The graph captures human intent. If you don't know why something was decided, ask. Never hallucinate rationale.
-4. **Always capture why.** When the user explains a reason, record it in the graph immediately. Conversation evaporates; graph persists.
+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.
 
 ### Failure States
@@ -126,6 +126,7 @@ You have broken Yggdrasil if you do any of the following:
 - \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
 
@@ -192,7 +193,14 @@ You are not allowed to edit or create source code without establishing graph cov
 - Option B \u2014 Blackbox: create a blackbox node at agreed granularity
 - Option C \u2014 Abort
 
-*Greenfield (new code):* Only Option A. Blackbox is forbidden for new code. Create nodes with full artifacts, then materialize.
+*Greenfield (new code):* Only Option A. Blackbox is forbidden for new code. Follow the graph-first workflow:
+
+1. Create aspects first (cross-cutting requirements the new code must satisfy)
+2. Create flows if the code participates in a business process
+3. Create nodes with full artifacts \u2014 responsibility, constraints, decisions, interface, logic
+4. Review the context package (\`yg build-context\`) \u2014 it is now the behavioral specification
+5. Implement code that satisfies the specification
+6. The graph specifies WHAT and WHY; the code implements HOW (framework APIs, library choices)
 
 After the user chooses, return to Step 1 and follow Step 2a.
 
@@ -226,6 +234,7 @@ 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\`.
 
 ### Bootstrap Mode
 
@@ -294,7 +303,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):** one node \u2192 local artifact; category of nodes \u2192 aspect content files; tech choice \u2192 \`config.yaml\` rationale field
+- **Decision (why + why NOT):** one node \u2192 \`decisions.md\` with format "Chose X over Y because Z"; category of nodes \u2192 aspect content files; tech choice \u2192 \`config.yaml\` rationale field. Always include rejected alternatives \u2014 they are the highest-value graph content.
 
 ### Creating Aspects
 
@@ -306,6 +315,12 @@ When you encounter information, route it to the correct location:
 
 Test: "Does this requirement apply to more than one node?" Yes \u2192 aspect. No \u2192 local artifact.
 
+**Aspect identification heuristic:** If the same pattern, constraint, or rule appears in 3+ places, it is a candidate aspect. Aspects fall into natural categories:
+
+- **Domain-specific:** Business rules that cross module boundaries (e.g., timezone handling, booking periods, currency rounding)
+- **Architectural:** Structural patterns with rationale (e.g., dual-rollback on provider failure, idempotency via key generation, fire-and-forget dispatch)
+- **Concurrency:** Shared concurrency strategies (e.g., pessimistic locking, retry-on-deadlock, optimistic versioning)
+
 ### Creating Flows
 
 - [ ] 1. Read \`schemas/flow.yaml\`
@@ -322,17 +337,18 @@ Test: "Does this describe what happens in the world, or only in the software?" I
 - **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?"
+- **Completeness test:** "If I delete the source file and give another agent ONLY the \`yg build-context\` output \u2014 can they recreate it correctly, understanding not just WHAT but WHY?" Test specifically: Can they explain rejected alternatives? Can they implement the correct algorithm (not a simplified version)? Can they argue for the current design against plausible alternatives?
 - **These rules are invariant.** No plan, guide, skill, or workflow may override them.
 
 ### CLI Reference
 
 \`\`\`
-yg preflight                        Unified diagnostic: journal + drift + status + validate.
+yg preflight [--quick]              Unified diagnostic: journal + drift + status + validate.
 yg owner --file <path>              Find the node that owns this file.
 yg build-context --node <path>      Assemble context package for this node.
 yg tree [--root <path>] [--depth N] Print graph structure.
 yg aspects                          List aspects with metadata (YAML output).
+yg flows                            List flows with metadata (YAML output).
 yg deps --node <path> [--depth N] [--type structural|event|all]
                                     Show dependencies.
 yg impact --node <path> --simulate  Simulate blast radius of a planned change.
@@ -340,9 +356,10 @@ yg impact --aspect <id>             Show all nodes where aspect is effective.
 yg impact --flow <name>             Show flow participants and descendants.
 yg status                           Graph health: nodes, coverage, drift summary.
 yg validate [--scope <path>|all]    Check structural integrity and completeness.
-yg drift [--scope <path>|all] [--drifted-only]
+yg drift [--scope <path>|all] [--drifted-only] [--limit <n>]
                                     Detect source and graph drift (bidirectional).
-yg drift-sync --node <path>         Record file hashes as new baseline.
+yg drift-sync --node <path> [--recursive] | --all
+                                    Record file hashes as new baseline.
 yg journal-read                     Read pending journal entries.
 yg journal-add --note "<content>" [--target <node_path>]
                                     Add a journal entry.
@@ -611,6 +628,7 @@ function getGraphSchemasDir() {
   return path2.join(packageRoot, "graph-schemas");
 }
 var GITIGNORE_CONTENT = `.journal.yaml
+.drift-state
 journals-archive/
 `;
 function registerInitCommand(program2) {
@@ -683,7 +701,7 @@ function registerInitCommand(program2) {
     process.stdout.write("  .yggdrasil/model/\n");
     process.stdout.write("  .yggdrasil/aspects/\n");
     process.stdout.write("  .yggdrasil/flows/\n");
-    process.stdout.write("  .yggdrasil/schemas/ (node, aspect, flow)\n");
+    process.stdout.write("  .yggdrasil/schemas/ (config, node, aspect, flow)\n");
     process.stdout.write(`  ${path2.relative(projectRoot, rulesPath)} (rules)
 
 `);
@@ -709,6 +727,9 @@ var DEFAULT_QUALITY = {
 async function parseConfig(filePath) {
   const content = await readFile3(filePath, "utf-8");
   const raw = parseYaml(content);
+  if (!raw || typeof raw !== "object") {
+    throw new Error(`config.yaml: file is empty or not a valid YAML mapping`);
+  }
   if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
     throw new Error(`config.yaml: missing or invalid 'name' field`);
   }
@@ -802,6 +823,9 @@ function isValidRelationType(t) {
 async function parseNodeYaml(filePath) {
   const content = await readFile4(filePath, "utf-8");
   const raw = parseYaml2(content);
+  if (!raw || typeof raw !== "object") {
+    throw new Error(`node.yaml at ${filePath}: file is empty or not a valid YAML mapping`);
+  }
   if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
     throw new Error(`node.yaml at ${filePath}: missing or empty 'name'`);
   }
@@ -922,6 +946,9 @@ async function parseAspect(aspectDir, aspectYamlPath, id) {
   }
   const content = await readFile6(aspectYamlPath, "utf-8");
   const raw = parseYaml3(content);
+  if (!raw || typeof raw !== "object") {
+    throw new Error(`Aspect file ${aspectYamlPath}: file is empty or not a valid YAML mapping`);
+  }
   if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
     throw new Error(`Aspect file ${aspectYamlPath}: missing or empty 'name'`);
   }
@@ -950,6 +977,9 @@ import { parse as parseYaml4 } from "yaml";
 async function parseFlow(flowDir, flowYamlPath) {
   const content = await readFile7(flowYamlPath, "utf-8");
   const raw = parseYaml4(content);
+  if (!raw || typeof raw !== "object") {
+    throw new Error(`flow.yaml at ${flowYamlPath}: file is empty or not a valid YAML mapping`);
+  }
   if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
     throw new Error(`flow.yaml at ${flowYamlPath}: missing or empty 'name'`);
   }
@@ -1036,6 +1066,9 @@ function normalizeProjectRelativePath(projectRoot, rawPath) {
   }
   return relative.split(path6.sep).join("/");
 }
+function projectRootFromGraph(yggRootPath) {
+  return path6.dirname(yggRootPath);
+}
 
 // src/core/graph-loader.ts
 function toModelPath(absolutePath, modelDir) {
@@ -1228,11 +1261,13 @@ async function buildContext(graph, nodePath) {
     layers.push(buildHierarchyLayer(ancestor, graph.config, graph));
   }
   layers.push(await buildOwnLayer(node, graph.config, graph.rootPath, graph));
+  const ancestorPaths = new Set(ancestors.map((a) => a.path));
   for (const relation of node.meta.relations ?? []) {
     const target = graph.nodes.get(relation.target);
     if (!target) {
       throw new Error(`Broken relation: ${nodePath} -> ${relation.target} (target not found)`);
     }
+    if (ancestorPaths.has(relation.target)) continue;
     if (STRUCTURAL_RELATION_TYPES.has(relation.type)) {
       layers.push(buildStructuralRelationLayer(target, relation, graph.config));
     } else if (EVENT_RELATION_TYPES.has(relation.type)) {
@@ -1548,6 +1583,7 @@ async function validate(graph, scope = "all") {
   issues.push(...checkRelationTargets(graph));
   issues.push(...checkNoCycles(graph));
   issues.push(...checkMappingOverlap(graph));
+  issues.push(...await checkMappingPathsExist(graph));
   issues.push(...checkBrokenFlowRefs(graph));
   issues.push(...checkFlowAspectIds(graph));
   issues.push(...await checkDirectoriesHaveNodeYaml(graph));
@@ -1557,13 +1593,29 @@ async function validate(graph, scope = "all") {
   let nodesScanned = graph.nodes.size;
   if (scope !== "all" && scope.trim()) {
     if (!graph.nodes.has(scope)) {
+      const parseError = (graph.nodeParseErrors ?? []).find(
+        (e) => e.nodePath === scope || scope.startsWith(e.nodePath + "/")
+      );
+      if (parseError) {
+        return {
+          issues: [{
+            severity: "error",
+            code: "E001",
+            rule: "invalid-node-yaml",
+            message: parseError.message,
+            nodePath: parseError.nodePath
+          }],
+          nodesScanned: 0
+        };
+      }
       return {
         issues: [{ severity: "error", rule: "invalid-scope", message: `Node not found: ${scope}` }],
         nodesScanned: 0
       };
     }
-    filtered = issues.filter((i) => !i.nodePath || i.nodePath === scope);
-    nodesScanned = 1;
+    const scopePrefix = scope + "/";
+    filtered = issues.filter((i) => !i.nodePath || i.nodePath === scope || i.nodePath.startsWith(scopePrefix));
+    nodesScanned = [...graph.nodes.keys()].filter((p) => p === scope || p.startsWith(scopePrefix)).length;
   }
   return { issues: filtered, nodesScanned };
 }
@@ -1820,6 +1872,9 @@ function arePathsOverlapping(pathA, pathB) {
   if (pathA === pathB) return true;
   return pathA.startsWith(pathB + "/") || pathB.startsWith(pathA + "/");
 }
+function isAncestorNode(possibleAncestor, possibleDescendant) {
+  return possibleDescendant.startsWith(possibleAncestor + "/");
+}
 function checkMappingOverlap(graph) {
   const issues = [];
   const ownership = [];
@@ -1835,6 +1890,9 @@ function checkMappingOverlap(graph) {
       const candidate = ownership[nestedIndex];
       if (current.nodePath === candidate.nodePath) continue;
       if (!arePathsOverlapping(current.mappingPath, candidate.mappingPath)) continue;
+      const isContainment = current.mappingPath !== candidate.mappingPath;
+      const isHierarchical = isAncestorNode(current.nodePath, candidate.nodePath) || isAncestorNode(candidate.nodePath, current.nodePath);
+      if (isContainment && isHierarchical) continue;
       issues.push({
         severity: "error",
         code: "E009",
@@ -1846,6 +1904,29 @@ function checkMappingOverlap(graph) {
   }
   return issues;
 }
+async function checkMappingPathsExist(graph) {
+  const issues = [];
+  const projectRoot = path9.dirname(graph.rootPath);
+  const { access: access4 } = await import("fs/promises");
+  for (const [nodePath, node] of graph.nodes) {
+    const mappingPaths = normalizeMappingPaths(node.meta.mapping);
+    for (const mp of mappingPaths) {
+      const absPath = path9.join(projectRoot, mp);
+      try {
+        await access4(absPath);
+      } catch {
+        issues.push({
+          severity: "warning",
+          code: "W012",
+          rule: "mapping-path-missing",
+          message: `Mapping path '${mp}' does not exist on disk`,
+          nodePath
+        });
+      }
+    }
+  }
+  return issues;
+}
 function getIncomingRelationSources(graph, nodePath) {
   const sources = [];
   for (const [srcPath, node] of graph.nodes) {
@@ -2077,16 +2158,27 @@ async function checkDirectoriesHaveNodeYaml(graph) {
     const hasNodeYaml = entries.some((e) => e.isFile() && e.name === "node.yaml");
     const dirName = path9.basename(dirPath);
     if (RESERVED_DIRS.has(dirName)) return;
-    const hasContent = entries.some((e) => e.isFile()) || entries.some((e) => e.isDirectory());
+    const hasFiles = entries.some((e) => e.isFile());
+    const hasSubdirs = entries.some((e) => e.isDirectory() && !RESERVED_DIRS.has(e.name) && !e.name.startsWith("."));
     const graphPath = segments.join("/");
-    if (hasContent && !hasNodeYaml && graphPath !== "") {
-      issues.push({
-        severity: "error",
-        code: "E015",
-        rule: "missing-node-yaml",
-        message: `Directory '${graphPath}' has content but no node.yaml`,
-        nodePath: graphPath
-      });
+    if (!hasNodeYaml && graphPath !== "") {
+      if (hasFiles) {
+        issues.push({
+          severity: "error",
+          code: "E015",
+          rule: "missing-node-yaml",
+          message: `Directory '${graphPath}' has files but no node.yaml`,
+          nodePath: graphPath
+        });
+      } else if (hasSubdirs) {
+        issues.push({
+          severity: "warning",
+          code: "W013",
+          rule: "directory-without-node",
+          message: `Directory '${graphPath}' has subdirectories but no node.yaml \u2014 consider creating a node`,
+          nodePath: graphPath
+        });
+      }
     }
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
@@ -2210,22 +2302,47 @@ function formatContextText(pkg2) {
 }
 
 // src/cli/build-context.ts
+function collectRelevantNodePaths(graph, nodePath) {
+  const relevant = /* @__PURE__ */ new Set();
+  const node = graph.nodes.get(nodePath);
+  if (!node) return relevant;
+  relevant.add(nodePath);
+  for (const ancestor of collectAncestors(node)) {
+    relevant.add(ancestor.path);
+  }
+  for (const rel of node.meta.relations ?? []) {
+    relevant.add(rel.target);
+  }
+  return relevant;
+}
 function registerBuildCommand(program2) {
   program2.command("build-context").description("Assemble a context package for one node").requiredOption("--node <node-path>", "Node path relative to .yggdrasil/model/").action(async (options) => {
     try {
       const graph = await loadGraph(process.cwd());
+      const nodePath = options.node.trim().replace(/^\.\//, "").replace(/\/$/, "");
+      const relevantNodes = collectRelevantNodePaths(graph, nodePath);
       const validationResult = await validate(graph, "all");
-      const structuralErrors = validationResult.issues.filter(
-        (issue) => issue.severity === "error"
+      const relevantErrors = validationResult.issues.filter(
+        (issue) => issue.severity === "error" && // Global errors (no nodePath) always block — e.g., E012 invalid config
+        (!issue.nodePath || relevantNodes.has(issue.nodePath))
       );
-      if (structuralErrors.length > 0) {
-        process.stderr.write(
-          `Error: build-context requires a structurally valid graph (${structuralErrors.length} errors found).
-`
-        );
+      if (relevantErrors.length > 0) {
+        const totalErrors = validationResult.issues.filter((i) => i.severity === "error").length;
+        const skippedErrors = totalErrors - relevantErrors.length;
+        let msg = `Error: build-context blocked by ${relevantErrors.length} error(s) affecting this node's context.
+`;
+        if (skippedErrors > 0) {
+          msg += `(${skippedErrors} unrelated error(s) in other nodes ignored.)
+`;
+        }
+        for (const err of relevantErrors) {
+          const loc = err.nodePath ? `${err.nodePath}: ` : "";
+          msg += `  ${err.code ?? ""} ${loc}${err.message}
+`;
+        }
+        process.stderr.write(msg);
         process.exit(1);
       }
-      const nodePath = options.node.trim().replace(/\/$/, "");
       const pkg2 = await buildContext(graph, nodePath);
       const warningThreshold = graph.config.quality?.context_budget.warning ?? 1e4;
       const errorThreshold = graph.config.quality?.context_budget.error ?? 2e4;
@@ -2254,7 +2371,8 @@ function registerValidateCommand(program2) {
   program2.command("validate").description("Validate graph structural integrity and completeness signals").option("--scope <scope>", "Scope: all or node-path (default: all)", "all").action(async (options) => {
     try {
       const graph = await loadGraph(process.cwd(), { tolerateInvalidConfig: true });
-      const scope = (options.scope ?? "all").trim() || "all";
+      const rawScope = (options.scope ?? "all").trim() || "all";
+      const scope = rawScope === "all" ? "all" : rawScope.replace(/^\.\//, "").replace(/\/+$/, "");
       const result = await validate(graph, scope);
       process.stdout.write(`${result.nodesScanned} nodes scanned
 
@@ -2298,12 +2416,17 @@ import chalk2 from "chalk";
 // src/io/drift-state-store.ts
 import { readFile as readFile11, writeFile as writeFile3 } from "fs/promises";
 import path10 from "path";
-import { stringify, parse } from "yaml";
+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 raw = parse(content);
+    let raw;
+    try {
+      raw = JSON.parse(content);
+    } catch {
+      raw = yamlParse(content);
+    }
     if (!raw || typeof raw !== "object") return {};
     const state = {};
     for (const [key, value] of Object.entries(raw)) {
@@ -2317,7 +2440,7 @@ async function readDriftState(yggRoot) {
   }
 }
 async function writeDriftState(yggRoot, state) {
-  const content = stringify(state, { lineWidth: 0 });
+  const content = JSON.stringify(state);
   await writeFile3(path10.join(yggRoot, DRIFT_STATE_FILE), content, "utf-8");
 }
 
@@ -2332,41 +2455,6 @@ async function hashFile(filePath) {
   const content = await readFile12(filePath);
   return createHash("sha256").update(content).digest("hex");
 }
-async function collectDirectoryFileHashes(directoryPath, rootDirectoryPath, options) {
-  let stack = options.gitignoreStack ?? [];
-  try {
-    const localContent = await readFile12(path11.join(directoryPath, ".gitignore"), "utf-8");
-    const localMatcher = ignoreFactory();
-    localMatcher.add(localContent);
-    stack = [...stack, { basePath: directoryPath, matcher: localMatcher }];
-  } catch {
-  }
-  const entries = await readdir5(directoryPath, { withFileTypes: true });
-  const result = [];
-  for (const entry of entries) {
-    const absoluteChildPath = path11.join(directoryPath, entry.name);
-    if (isIgnoredByStack(absoluteChildPath, stack)) {
-      continue;
-    }
-    if (entry.isDirectory()) {
-      const nested = await collectDirectoryFileHashes(
-        absoluteChildPath,
-        rootDirectoryPath,
-        { projectRoot: options.projectRoot, gitignoreStack: stack }
-      );
-      result.push(...nested);
-      continue;
-    }
-    if (!entry.isFile()) {
-      continue;
-    }
-    result.push({
-      path: path11.relative(rootDirectoryPath, absoluteChildPath),
-      hash: await hashFile(absoluteChildPath)
-    });
-  }
-  return result;
-}
 async function loadRootGitignoreStack(projectRoot) {
   if (!projectRoot) return [];
   try {
@@ -2389,33 +2477,95 @@ function isIgnoredByStack(candidatePath, stack) {
 function hashString(content) {
   return createHash("sha256").update(content).digest("hex");
 }
-async function hashTrackedFiles(projectRoot, trackedFiles) {
+async function hashTrackedFiles(projectRoot, trackedFiles, storedFileData, excludePrefixes) {
   const fileHashes = {};
+  const fileMtimes = {};
   const gitignoreStack = await loadRootGitignoreStack(projectRoot);
+  const allFiles = [];
   for (const tf of trackedFiles) {
     const absPath = path11.join(projectRoot, tf.path);
     try {
       const st = await stat3(absPath);
       if (st.isDirectory()) {
-        const dirHashes = await collectDirectoryFileHashes(absPath, absPath, {
+        const dirEntries = await collectDirectoryFilePaths(absPath, absPath, {
           projectRoot,
           gitignoreStack
         });
-        for (const entry of dirHashes) {
-          const fullRelPath = path11.join(tf.path, entry.path).replace(/\\/g, "/");
-          fileHashes[fullRelPath] = entry.hash;
+        for (const entry of dirEntries) {
+          allFiles.push({
+            relPath: path11.join(tf.path, entry.relPath).replace(/\\/g, "/"),
+            absPath: entry.absPath,
+            mtimeMs: entry.mtimeMs
+          });
         }
       } else {
-        fileHashes[tf.path] = await hashFile(absPath);
+        allFiles.push({ relPath: tf.path, absPath, mtimeMs: st.mtimeMs });
       }
     } catch {
       continue;
     }
   }
+  const filtered = excludePrefixes?.length ? allFiles.filter((entry) => !excludePrefixes.some((prefix) => entry.relPath === prefix || entry.relPath.startsWith(prefix + "/"))) : allFiles;
+  const dirty = [];
+  for (const entry of filtered) {
+    const storedMtime = storedFileData?.mtimes[entry.relPath];
+    const storedHash = storedFileData?.hashes[entry.relPath];
+    if (storedMtime !== void 0 && storedHash !== void 0 && entry.mtimeMs === storedMtime) {
+      fileHashes[entry.relPath] = storedHash;
+    } else {
+      dirty.push(entry);
+    }
+    fileMtimes[entry.relPath] = entry.mtimeMs;
+  }
+  const BATCH_SIZE = 256;
+  for (let i = 0; i < dirty.length; i += BATCH_SIZE) {
+    const batch = dirty.slice(i, i + BATCH_SIZE);
+    const hashes = await Promise.all(batch.map((e) => hashFile(e.absPath)));
+    for (let j = 0; j < batch.length; j++) {
+      fileHashes[batch[j].relPath] = hashes[j];
+    }
+  }
   const sorted = Object.entries(fileHashes).sort(([a], [b]) => a.localeCompare(b));
   const digest = sorted.map(([p, h]) => `${p}:${h}`).join("\n");
   const canonicalHash = hashString(digest);
-  return { canonicalHash, fileHashes };
+  return { canonicalHash, fileHashes, fileMtimes };
+}
+async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, options) {
+  let stack = options.gitignoreStack ?? [];
+  try {
+    const localContent = await readFile12(path11.join(directoryPath, ".gitignore"), "utf-8");
+    const localMatcher = ignoreFactory();
+    localMatcher.add(localContent);
+    stack = [...stack, { basePath: directoryPath, matcher: localMatcher }];
+  } catch {
+  }
+  const entries = await readdir5(directoryPath, { withFileTypes: true });
+  const dirs = [];
+  const files = [];
+  for (const entry of entries) {
+    const absoluteChildPath = path11.join(directoryPath, entry.name);
+    if (isIgnoredByStack(absoluteChildPath, stack)) continue;
+    if (entry.isDirectory()) dirs.push(absoluteChildPath);
+    else if (entry.isFile()) files.push(absoluteChildPath);
+  }
+  const [dirResults, fileStats] = await Promise.all([
+    Promise.all(dirs.map((d) => collectDirectoryFilePaths(d, rootDirectoryPath, {
+      projectRoot: options.projectRoot,
+      gitignoreStack: stack
+    }))),
+    Promise.all(files.map(async (f) => {
+      const fileStat = await stat3(f);
+      return {
+        relPath: path11.relative(rootDirectoryPath, f),
+        absPath: f,
+        mtimeMs: fileStat.mtimeMs
+      };
+    }))
+  ]);
+  const result = [];
+  for (const nested of dirResults) result.push(...nested);
+  result.push(...fileStats);
+  return result;
 }
 
 // src/core/context-files.ts
@@ -2511,12 +2661,32 @@ function collectParticipatingFlows2(graph, node, ancestors) {
 // src/core/drift-detector.ts
 import { access } from "fs/promises";
 import path13 from "path";
+function getChildMappingExclusions(graph, nodePath) {
+  const node = graph.nodes.get(nodePath);
+  if (!node) return [];
+  const parentMappings = normalizeMappingPaths(node.meta.mapping);
+  if (parentMappings.length === 0) return [];
+  const exclusions = [];
+  for (const [childPath, childNode] of graph.nodes) {
+    if (childPath === nodePath) continue;
+    if (!childPath.startsWith(nodePath + "/")) continue;
+    const childMappings = normalizeMappingPaths(childNode.meta.mapping);
+    for (const cm of childMappings) {
+      for (const pm of parentMappings) {
+        if (cm === pm || cm.startsWith(pm + "/")) {
+          exclusions.push(cm);
+        }
+      }
+    }
+  }
+  return exclusions;
+}
 async function detectDrift(graph, filterNodePath) {
   const projectRoot = path13.dirname(graph.rootPath);
   const driftState = await readDriftState(graph.rootPath);
   const entries = [];
   for (const [nodePath, node] of graph.nodes) {
-    if (filterNodePath && nodePath !== filterNodePath) continue;
+    if (filterNodePath && nodePath !== filterNodePath && !nodePath.startsWith(filterNodePath + "/")) continue;
     const mapping = node.meta.mapping;
     if (!mapping) continue;
     const mappingPaths = normalizeMappingPaths(mapping);
@@ -2541,7 +2711,9 @@ async function detectDrift(graph, filterNodePath) {
       continue;
     }
     const trackedFiles = collectTrackedFiles(node, graph);
-    const { canonicalHash, fileHashes } = await hashTrackedFiles(projectRoot, trackedFiles);
+    const excludePrefixes = getChildMappingExclusions(graph, nodePath);
+    const storedFileData = storedEntry.files ? { hashes: storedEntry.files, mtimes: storedEntry.mtimes ?? {} } : void 0;
+    const { canonicalHash, fileHashes } = await hashTrackedFiles(projectRoot, trackedFiles, storedFileData, excludePrefixes);
     if (canonicalHash === storedEntry.hash) {
       entries.push({ nodePath, status: "ok" });
       continue;
@@ -2614,20 +2786,29 @@ async function syncDriftState(graph, nodePath) {
   if (!node) throw new Error(`Node not found: ${nodePath}`);
   if (!node.meta.mapping) throw new Error(`Node has no mapping: ${nodePath}`);
   const trackedFiles = collectTrackedFiles(node, graph);
-  const { canonicalHash, fileHashes } = await hashTrackedFiles(projectRoot, trackedFiles);
-  const state = await readDriftState(graph.rootPath);
-  const previousHash = state[nodePath]?.hash;
-  state[nodePath] = { hash: canonicalHash, files: fileHashes };
-  await writeDriftState(graph.rootPath, state);
+  const excludePrefixes = getChildMappingExclusions(graph, nodePath);
+  const existingState = await readDriftState(graph.rootPath);
+  const existingEntry = existingState[nodePath];
+  const storedFileData = existingEntry?.files ? { hashes: existingEntry.files, mtimes: existingEntry.mtimes ?? {} } : void 0;
+  const { canonicalHash, fileHashes, fileMtimes } = await hashTrackedFiles(projectRoot, trackedFiles, storedFileData, excludePrefixes);
+  const previousHash = existingEntry?.hash;
+  existingState[nodePath] = { hash: canonicalHash, files: fileHashes, mtimes: fileMtimes };
+  for (const key of Object.keys(existingState)) {
+    if (!graph.nodes.has(key)) {
+      delete existingState[key];
+    }
+  }
+  await writeDriftState(graph.rootPath, existingState);
   return { previousHash, currentHash: canonicalHash };
 }
 
 // src/cli/drift.ts
 function registerDriftCommand(program2) {
-  program2.command("drift").description("Detect divergences between graph and mapped files").option("--scope <scope>", 'Scope: "all" or node path', "all").option("--drifted-only", "Show only nodes with drift (hide ok entries)").action(async (opts) => {
+  program2.command("drift").description("Detect divergences between graph and mapped files").option("--scope <scope>", 'Scope: "all" or node path', "all").option("--drifted-only", "Show only nodes with drift (hide ok entries)").option("--limit <n>", "Maximum number of entries to show per section", parseInt).action(async (opts) => {
     try {
       const graph = await loadGraph(process.cwd());
-      const scope = (opts.scope ?? "all").trim() || "all";
+      const rawScope = (opts.scope ?? "all").trim() || "all";
+      const scope = rawScope === "all" ? "all" : rawScope.replace(/^\.\//, "").replace(/\/+$/, "");
       if (scope !== "all") {
         const node = graph.nodes.get(scope);
         if (!node) {
@@ -2635,7 +2816,8 @@ function registerDriftCommand(program2) {
 `);
           process.exit(1);
         }
-        if (!node.meta.mapping) {
+        const hasAnyMapping = node.meta.mapping || [...graph.nodes.entries()].some(([p, n]) => p.startsWith(scope + "/") && n.meta.mapping);
+        if (!hasAnyMapping) {
           process.stderr.write(`Error: Node has no mapping: ${scope}
 `);
           process.exit(1);
@@ -2643,7 +2825,7 @@ function registerDriftCommand(program2) {
       }
       const scopeNode = scope === "all" ? void 0 : scope;
       const report = await detectDrift(graph, scopeNode);
-      printReport(report, opts.driftedOnly ?? false);
+      printReport(report, opts.driftedOnly ?? false, opts.limit);
       const hasIssues = report.sourceDriftCount > 0 || report.graphDriftCount > 0 || report.fullDriftCount > 0 || report.missingCount > 0 || report.unmaterializedCount > 0;
       process.exit(hasIssues ? 1 : 0);
     } catch (error) {
@@ -2653,13 +2835,23 @@ function registerDriftCommand(program2) {
     }
   });
 }
-function printReport(report, driftedOnly) {
+function printReport(report, driftedOnly, limit) {
   const sourceEntries = classifyForSection(report.entries, "source", driftedOnly);
   const graphEntries = classifyForSection(report.entries, "graph", driftedOnly);
+  const sourceShown = limit !== void 0 ? sourceEntries.slice(0, limit) : sourceEntries;
+  const graphShown = limit !== void 0 ? graphEntries.slice(0, limit) : graphEntries;
   process.stdout.write("Source drift:\n");
-  printSectionEntries(sourceEntries, "source");
+  printSectionEntries(sourceShown, "source");
+  if (limit !== void 0 && sourceEntries.length > limit) {
+    process.stdout.write(chalk2.dim(`  ... ${sourceEntries.length - limit} more (${sourceEntries.length} total)
+`));
+  }
   process.stdout.write("\nGraph drift:\n");
-  printSectionEntries(graphEntries, "graph");
+  printSectionEntries(graphShown, "graph");
+  if (limit !== void 0 && graphEntries.length > limit) {
+    process.stdout.write(chalk2.dim(`  ... ${graphEntries.length - limit} more (${graphEntries.length} total)
+`));
+  }
   const parts = [
     `${report.sourceDriftCount} source-drift`,
     `${report.graphDriftCount} graph-drift`,
@@ -2745,17 +2937,49 @@ function printChangedFiles(entry, section) {
 // src/cli/drift-sync.ts
 import chalk3 from "chalk";
 function registerDriftSyncCommand(program2) {
-  program2.command("drift-sync").description("Record current file hash after resolving drift").requiredOption("--node <path>", "Node path to sync").action(async (options) => {
+  program2.command("drift-sync").description("Record current file hash after resolving drift").option("--node <path>", "Node path to sync").option("--recursive", "Also sync all descendant nodes").option("--all", "Sync all nodes with mappings").action(async (options) => {
     try {
+      if (!options.node && !options.all) {
+        process.stderr.write("Error: either '--node <path>' or '--all' is required\n");
+        process.exit(1);
+      }
       const graph = await loadGraph(process.cwd());
-      const nodePath = options.node.trim().replace(/\/$/, "");
-      const { previousHash, currentHash } = await syncDriftState(graph, nodePath);
-      process.stdout.write(chalk3.green(`Synchronized: ${nodePath}
+      let nodesToSync;
+      if (options.all) {
+        nodesToSync = [...graph.nodes.entries()].filter(([, n]) => normalizeMappingPaths(n.meta.mapping).length > 0).map(([p]) => p).sort();
+      } else {
+        const nodePath = options.node.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+        if (!graph.nodes.has(nodePath)) {
+          await syncDriftState(graph, nodePath);
+          return;
+        }
+        nodesToSync = [nodePath];
+        if (options.recursive) {
+          const prefix = nodePath + "/";
+          for (const [p] of graph.nodes) {
+            if (p.startsWith(prefix)) {
+              nodesToSync.push(p);
+            }
+          }
+          nodesToSync.sort();
+        }
+      }
+      for (const np of nodesToSync) {
+        const node = graph.nodes.get(np);
+        if (normalizeMappingPaths(node.meta.mapping).length === 0) {
+          if (!options.all && !options.recursive && np === options.node) {
+            await syncDriftState(graph, np);
+          }
+          continue;
+        }
+        const { previousHash, currentHash } = await syncDriftState(graph, np);
+        process.stdout.write(chalk3.green(`Synchronized: ${np}
 `));
-      process.stdout.write(
-        `  Hash: ${previousHash ? previousHash.slice(0, 8) : "none"} -> ${currentHash.slice(0, 8)}
+        process.stdout.write(
+          `  Hash: ${previousHash ? previousHash.slice(0, 8) : "none"} -> ${currentHash.slice(0, 8)}
 `
-      );
+        );
+      }
     } catch (error) {
       process.stderr.write(`Error: ${error.message}
 `);
@@ -2872,10 +3096,10 @@ function registerTreeCommand(program2) {
       let roots;
       let showProjectName;
       if (options.root?.trim()) {
-        const path17 = options.root.trim().replace(/\/$/, "");
-        const node = graph.nodes.get(path17);
+        const path18 = options.root.trim().replace(/\/$/, "");
+        const node = graph.nodes.get(path18);
         if (!node) {
-          process.stderr.write(`Error: path '${path17}' not found
+          process.stderr.write(`Error: path '${path18}' not found
 `);
           process.exit(1);
         }
@@ -2919,6 +3143,8 @@ function printNode(node, prefix, isLast, depth, maxDepth) {
 }
 
 // src/cli/owner.ts
+import path14 from "path";
+import { access as access2 } from "fs/promises";
 function normalizeForMatch(inputPath) {
   return inputPath.replace(/\\/g, "/").replace(/\/+$/, "");
 }
@@ -2943,12 +3169,28 @@ function findOwner(graph, projectRoot, rawPath) {
 function registerOwnerCommand(program2) {
   program2.command("owner").description("Find which graph node owns a source file").requiredOption("--file <path>", "File path (relative to repository root)").action(async (options) => {
     try {
-      const projectRoot = process.cwd();
-      const graph = await loadGraph(projectRoot);
-      const result = findOwner(graph, projectRoot, options.file);
+      const cwd = process.cwd();
+      const graph = await loadGraph(cwd);
+      const repoRoot = projectRootFromGraph(graph.rootPath);
+      const rawPath = options.file.trim();
+      const absolute = path14.resolve(cwd, rawPath);
+      const repoRelative = path14.relative(repoRoot, absolute).split(path14.sep).join("/");
+      const result = findOwner(graph, repoRoot, repoRelative);
       if (!result.nodePath) {
-        process.stdout.write(`${result.file} -> no graph coverage
+        const absPath = path14.resolve(repoRoot, result.file);
+        let exists = true;
+        try {
+          await access2(absPath);
+        } catch {
+          exists = false;
+        }
+        if (exists) {
+          process.stdout.write(`${result.file} -> no graph coverage
+`);
+        } else {
+          process.stdout.write(`${result.file} -> no graph coverage (file not found)
 `);
+        }
       } else {
         process.stdout.write(`${result.file} -> ${result.nodePath}
 `);
@@ -2963,7 +3205,7 @@ function registerOwnerCommand(program2) {
 
 // src/core/dependency-resolver.ts
 import { execSync } from "child_process";
-import path14 from "path";
+import path15 from "path";
 var STRUCTURAL_RELATION_TYPES3 = /* @__PURE__ */ new Set(["uses", "calls", "extends", "implements"]);
 var EVENT_RELATION_TYPES2 = /* @__PURE__ */ new Set(["emits", "listens"]);
 function filterRelationType(relType, filter) {
@@ -3023,7 +3265,7 @@ function registerDepsCommand(program2) {
     try {
       const graph = await loadGraph(process.cwd());
       const typeFilter = options.type === "structural" || options.type === "event" || options.type === "all" ? options.type : "all";
-      const nodePath = options.node.trim().replace(/\/$/, "");
+      const nodePath = options.node.trim().replace(/^\.\//, "").replace(/\/+$/, "");
       const text = formatDependencyTree(graph, nodePath, {
         depth: options.depth,
         relationType: typeFilter
@@ -3040,7 +3282,7 @@ function registerDepsCommand(program2) {
 // src/core/graph-from-git.ts
 import { mkdtemp, rm } from "fs/promises";
 import { tmpdir } from "os";
-import path15 from "path";
+import path16 from "path";
 import { execSync as execSync2 } from "child_process";
 async function loadGraphFromRef(projectRoot, ref = "HEAD") {
   const yggPath = ".yggdrasil";
@@ -3051,8 +3293,8 @@ async function loadGraphFromRef(projectRoot, ref = "HEAD") {
     return null;
   }
   try {
-    tmpDir = await mkdtemp(path15.join(tmpdir(), "ygg-git-"));
-    const archivePath = path15.join(tmpDir, "archive.tar");
+    tmpDir = await mkdtemp(path16.join(tmpdir(), "ygg-git-"));
+    const archivePath = path16.join(tmpDir, "archive.tar");
     execSync2(`git archive ${ref} ${yggPath} -o "${archivePath}"`, {
       cwd: projectRoot,
       stdio: "pipe"
@@ -3122,14 +3364,14 @@ function buildTransitiveChains(targetNode, direct, allDependents, reverse) {
   }
   const chains = [];
   for (const node of transitiveOnly) {
-    const path17 = [];
+    const path18 = [];
     let current = node;
     while (current) {
-      path17.unshift(current);
+      path18.unshift(current);
       current = parent.get(current);
     }
-    if (path17.length >= 3) {
-      chains.push(path17.slice(1).map((p) => `<- ${p}`).join(" "));
+    if (path18.length >= 3) {
+      chains.push(path18.slice(1).map((p) => `<- ${p}`).join(" "));
     }
   }
   return chains.sort();
@@ -3331,7 +3573,7 @@ function registerImpactCommand(program2) {
           await handleFlowImpact(graph, options.flow.trim(), options.simulate);
           return;
         }
-        const nodePath = options.node.trim().replace(/\/$/, "");
+        const nodePath = options.node.trim().replace(/^\.\//, "").replace(/\/+$/, "");
         if (!graph.nodes.has(nodePath)) {
           process.stderr.write(`Node not found: ${nodePath}
 `);
@@ -3463,14 +3705,47 @@ function registerAspectsCommand(program2) {
   });
 }
 
+// src/cli/flows.ts
+import { stringify as yamlStringify2 } from "yaml";
+function registerFlowsCommand(program2) {
+  program2.command("flows").description("List flows with metadata (YAML output)").action(async () => {
+    try {
+      const yggRoot = await findYggRoot(process.cwd());
+      const graph = await loadGraph(yggRoot);
+      const output = graph.flows.sort((a, b) => a.name.localeCompare(b.name)).map((flow) => {
+        const entry = {
+          name: flow.name,
+          participants: flow.nodes.length,
+          nodes: flow.nodes.sort()
+        };
+        if (flow.aspects && flow.aspects.length > 0) entry.aspects = flow.aspects;
+        return entry;
+      });
+      process.stdout.write(yamlStringify2(output));
+    } catch (error) {
+      const err = error;
+      if (err.code === "ENOENT") {
+        process.stderr.write(
+          `Error: No .yggdrasil/ directory found. Run 'yg init' first.
+`
+        );
+      } else {
+        process.stderr.write(`Error: ${error.message}
+`);
+      }
+      process.exit(1);
+    }
+  });
+}
+
 // src/io/journal-store.ts
-import { readFile as readFile13, writeFile as writeFile4, mkdir as mkdir3, rename, access as access2 } from "fs/promises";
+import { readFile as readFile13, writeFile as writeFile4, mkdir as mkdir3, rename, access as access3 } from "fs/promises";
 import { parse as parseYaml6, stringify as stringifyYaml } from "yaml";
-import path16 from "path";
+import path17 from "path";
 var JOURNAL_FILE = ".journal.yaml";
 var ARCHIVE_DIR = "journals-archive";
 async function readJournal(yggRoot) {
-  const filePath = path16.join(yggRoot, JOURNAL_FILE);
+  const filePath = path17.join(yggRoot, JOURNAL_FILE);
   try {
     const content = await readFile13(filePath, "utf-8");
     const raw = parseYaml6(content);
@@ -3485,26 +3760,26 @@ async function appendJournalEntry(yggRoot, note, target) {
   const at = (/* @__PURE__ */ new Date()).toISOString();
   const entry = target ? { at, target, note } : { at, note };
   entries.push(entry);
-  const filePath = path16.join(yggRoot, JOURNAL_FILE);
+  const filePath = path17.join(yggRoot, JOURNAL_FILE);
   const content = stringifyYaml({ entries });
   await writeFile4(filePath, content, "utf-8");
   return entry;
 }
 async function archiveJournal(yggRoot) {
-  const journalPath = path16.join(yggRoot, JOURNAL_FILE);
+  const journalPath = path17.join(yggRoot, JOURNAL_FILE);
   try {
-    await access2(journalPath);
+    await access3(journalPath);
   } catch {
     return null;
   }
   const entries = await readJournal(yggRoot);
   if (entries.length === 0) return null;
-  const archiveDir = path16.join(yggRoot, ARCHIVE_DIR);
+  const archiveDir = path17.join(yggRoot, ARCHIVE_DIR);
   await mkdir3(archiveDir, { recursive: true });
   const now = /* @__PURE__ */ new Date();
   const timestamp = `${now.getUTCFullYear()}${String(now.getUTCMonth() + 1).padStart(2, "0")}${String(now.getUTCDate()).padStart(2, "0")}-${String(now.getUTCHours()).padStart(2, "0")}${String(now.getUTCMinutes()).padStart(2, "0")}${String(now.getUTCSeconds()).padStart(2, "0")}`;
   const archiveName = `.journal.${timestamp}.yaml`;
-  const archivePath = path16.join(archiveDir, archiveName);
+  const archivePath = path17.join(archiveDir, archiveName);
   await rename(journalPath, archivePath);
   return { archiveName, entryCount: entries.length };
 }
@@ -3582,14 +3857,13 @@ function registerJournalArchiveCommand(program2) {
 
 // src/cli/preflight.ts
 function registerPreflightCommand(program2) {
-  program2.command("preflight").description("Unified diagnostic report: journal, drift, status, validation").action(async () => {
+  program2.command("preflight").description("Unified diagnostic report: journal, drift, status, validation").option("--quick", "Skip drift detection for faster results").action(async (options) => {
     try {
       const cwd = process.cwd();
       const graph = await loadGraph(cwd);
       const yggRoot = await findYggRoot(cwd);
       const journalEntries = await readJournal(yggRoot);
-      const drift = await detectDrift(graph);
-      const driftedEntries = drift.entries.filter((e) => e.status !== "ok");
+      const driftedEntries = options.quick ? [] : (await detectDrift(graph)).entries.filter((e) => e.status !== "ok");
       const nodeCount = graph.nodes.size;
       const aspectCount = graph.aspects.length;
       const flowCount = graph.flows.length;
@@ -3613,7 +3887,9 @@ function registerPreflightCommand(program2) {
         }
       }
       lines.push("");
-      if (driftedEntries.length === 0) {
+      if (options.quick) {
+        lines.push("Drift:      skipped (--quick)");
+      } else if (driftedEntries.length === 0) {
         lines.push("Drift:      clean");
       } else {
         lines.push(`Drift:      ${driftedEntries.length} nodes need attention`);
@@ -3625,6 +3901,12 @@ function registerPreflightCommand(program2) {
       lines.push(
         `Status:     ${nodeCount} nodes, ${aspectCount} aspects, ${flowCount} flows, ${mappedPathCount} mapped paths`
       );
+      if (nodeCount === 0) {
+        lines.push("");
+        lines.push("            \u26A1 No nodes found. Enter BOOTSTRAP MODE:");
+        lines.push("            Create nodes under .yggdrasil/model/ for your active work area.");
+        lines.push("            See: yg help build-context");
+      }
       lines.push("");
       if (errors.length === 0 && warnings.length === 0) {
         lines.push("Validation: clean");
@@ -3635,12 +3917,13 @@ function registerPreflightCommand(program2) {
         lines.push(`Validation: ${parts.join(", ")}`);
         for (const issue of [...errors, ...warnings]) {
           const code = issue.code ? `[${issue.code}] ` : "";
-          lines.push(`            - ${code}${issue.message}`);
+          const loc = issue.nodePath ? `${issue.nodePath} -> ` : "";
+          lines.push(`            - ${code}${loc}${issue.message}`);
         }
       }
       lines.push("");
       process.stdout.write(lines.join("\n"));
-      const hasIssues = journalEntries.length > 0 || driftedEntries.length > 0 || errors.length > 0;
+      const hasIssues = journalEntries.length > 0 || !options.quick && driftedEntries.length > 0 || errors.length > 0;
       process.exit(hasIssues ? 1 : 0);
     } catch (error) {
       process.stderr.write(`Error: ${error.message}
@@ -3670,6 +3953,7 @@ registerOwnerCommand(program);
 registerDepsCommand(program);
 registerImpactCommand(program);
 registerAspectsCommand(program);
+registerFlowsCommand(program);
 registerJournalAddCommand(program);
 registerJournalReadCommand(program);
 registerJournalArchiveCommand(program);