@chrisdudek/yg 0.2.1 → 0.3.1

package/dist/bin.js

@@ -123,6 +123,7 @@ You have fundamentally broken Yggdrasil if you do any of the following:
 - \u274C You ran \`yg drift-sync\` before updating graph artifacts.
 - \u274C You ran \`yg drift-sync\` after a graph-only change without verifying source files.
 - \u274C You used Blackbox coverage for greenfield/new code.
+- \u274C You answered a question about a mapped file/area without running \`yg build-context\` when the path was known.
 
 ---
 
@@ -133,15 +134,23 @@ You do not need explicit "session" commands. Follow these conversational trigger
 ### A. Preflight (First message of the conversation)
 Always execute these commands before doing anything else. *(Exception: If the user's request is clearly read-only, run ONLY step 1).* **Read-only** means the user asks only for explanation, clarification, analysis, or evaluation \u2014 no code or graph modification will occur. Examples: "explain this", "evaluate X", "what does Y do?", "analyze Z". If unsure, run full preflight.
 1. \`yg journal-read\` -> If entries exist, consolidate them into the graph, then \`yg journal-archive\`.
-2. \`yg drift\` -> If divergence is detected, present states (\`ok\`, \`drift\`, \`missing\`, \`unmaterialized\`). Ask the user: Absorb (update graph) or Reject (re-materialize code from graph)?
+2. \`yg drift\` -> If **drift** (code changed, graph baseline stale): run \`yg drift-sync\` for each affected node. Do NOT ask the user \u2014 they do not need to know this step. If **missing** or **unmaterialized**: report and ask the user how to proceed.
 3. \`yg status\` -> Report graph health.
 4. \`yg validate\` -> If W008 stale-knowledge appears, update the knowledge artifacts to reflect current node state.
 
-### B. Session Verification (Wrap-up)
-Triggered by phrases like: "we're done", "wrap up", "that's enough", "done".
+### B. Answering Questions (When a specific file or area is known)
+When the user asks a question and you know (or can infer) which file or area of the codebase it concerns:
+1. Run \`yg owner --file <path>\` for the relevant file(s).
+2. **If owner FOUND:** Run \`yg build-context --node <node_path>\` and base your answer on that context. Do NOT answer from grep/search alone \u2014 the graph provides intent, constraints, and relations that yield better answers.
+3. **If owner NOT FOUND:** The file is outside the graph (e.g. third-party code, user's theme/plugin, unmapped area). You may answer from grep/search, but state that the answer is not graph-based.
+
+This applies even when you are **not modifying files** \u2014 e.g. when providing code snippets to paste elsewhere, explaining behavior, or suggesting hooks. If the question touches mapped code, build-context first.
+
+### C. Session Verification (Wrap-up)
+Triggered by phrases like: "we're done", "wrap up", "that's enough", "done", "ok".
 **Note: The graph should ALREADY be up to date. If the graph requires massive updates at this stage, YOU HAVE FAILED.**
 1. If iterative journal mode was used: consolidate notes to the graph, then \`yg journal-archive\`.
-2. \`yg drift\` -> Check if files changed manually during the conversation.
+2. \`yg drift\` -> If drift detected, run \`yg drift-sync\` for each affected node. Do NOT ask \u2014 absorb automatically.
 3. \`yg validate\` -> Fix any structural errors.
 4. Report exactly what nodes and files were changed.
 
@@ -254,6 +263,7 @@ When mapping a file, execute this mental routing:
 * **Routing:**
   * If it calls another module: Add an outgoing structural \`relation\` in \`node.yaml\`. (The engine will automatically fetch the target's structural-context artifacts: responsibility, interface, constraints, errors).
   * If it participates in an end-to-end process: Do not explain the whole process locally. Ensure the node is listed in \`.yggdrasil/flows/<flow_name>/flow.yaml\`. The engine will attach the flow knowledge automatically.
+* **Flows \u2014 writing flow content:** When creating or editing flow artifacts (e.g. \`description.md\` in \`flows/<name>/\`), write business-first: describe the process from user/business perspective. Technical details only as inserts when they clarify the flow. Not technical-first with business inserts.
 
 ### Layer 3: Domain Context (Hierarchy)
 * **What goes here:** Business rules shared by a family of nodes.
@@ -1244,7 +1254,7 @@ async function buildContext(graph, nodePath) {
       }
     }
   }
-  for (const flow of collectParticipatingFlows(graph, nodePath)) {
+  for (const flow of collectParticipatingFlows(graph, node)) {
     layers.push(buildFlowLayer(flow));
     for (const kPath of flow.knowledge ?? []) {
       const norm = kPath.replace(/\/$/, "");
@@ -1306,8 +1316,9 @@ function collectKnowledgeItems(graph, nodePath, nodeTags, seenKnowledge) {
   }
   return result;
 }
-function collectParticipatingFlows(graph, nodePath) {
-  return graph.flows.filter((f) => f.nodes.includes(nodePath));
+function collectParticipatingFlows(graph, node) {
+  const paths = /* @__PURE__ */ new Set([node.path, ...collectAncestors(node).map((a) => a.path)]);
+  return graph.flows.filter((f) => f.nodes.some((n) => paths.has(n)));
 }
 function buildGlobalLayer(config) {
   let content = `**Project:** ${config.name}